Manage Product Files

Use Code Storage as the version control system for a product’s files. Your application uses the SDK to store each change as a commit, to read one exact version, and to show history. A user edits the files through your product interface and never uses Git. Your application validates the complete file set, saves it, applies that exact version, and records it as the active revision. The active revision is the exact commit that the product currently uses.

Provision the managed repository

For each product, create one managed repository in Code Storage. Save the repository id on your product record, so a later request finds the right repository. The examples use products and productFiles for services that you own. Set PIERRE_ORG and PIERRE_PRIVATE_KEY as shown in the Quick Start.

import { GitStorage } from '@pierre/storage';

const storage = new GitStorage({
  name: process.env.PIERRE_ORG!,
  key: process.env.PIERRE_PRIVATE_KEY!,
});

const product = await products.create({ name: 'Support agent' });
const repo = await storage.createRepo({ id: `products/${product.id}` });

await products.update(product.id, { repositoryId: repo.id });

import os

from pierre_storage import GitStorage

storage_client = GitStorage({
    "name": os.environ["PIERRE_ORG"],
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

product = await products.create(name="Support agent")
repo = await storage_client.create_repo(id=f"products/{product.id}")

await products.update(product.id, {"repository_id": repo.id})

import "os"

ctx := context.Background()

client, err := storage.NewClient(storage.Options{
	Name: os.Getenv("PIERRE_ORG"),
	Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
})
if err != nil {
	return err
}

product, err := products.Create(ctx, "Support agent")
if err != nil {
	return err
}
repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: fmt.Sprintf("products/%s", product.ID),
})
if err != nil {
	return err
}

err = products.Update(ctx, product.ID, ProductUpdate{RepositoryID: repo.ID})

Create the first active revision

Build and validate the complete file set before you save it. Save the files as one commit. Apply that exact commit, then record it as the active revision.

const initialFiles = await productFiles.buildInitial(product.id);

let change = repo.createCommit({
  targetBranch: 'main',
  commitMessage: 'Create product definition',
  author: { name: 'Product Service', email: 'product-service@example.com' },
});

for (const [path, contents] of Object.entries(initialFiles)) {
  change = change.addFileFromString(path, contents);
}

const committed = await change.send();
const archive = await repo.getArchiveStream({ ref: committed.commitSha });

await productFiles.apply(archive.body!, committed.commitSha);
await products.update(product.id, {
  activeRevision: committed.commitSha,
  headRevision: committed.commitSha,
});

initial_files = await product_files.build_initial(product.id)

change = repo.create_commit(
    target_branch="main",
    commit_message="Create product definition",
    author={"name": "Product Service", "email": "product-service@example.com"},
)

for path, contents in initial_files.items():
    change = change.add_file_from_string(path, contents)

committed = await change.send()
archive = await repo.get_archive_stream(ref=committed["commit_sha"])
archive_bytes = await archive.aread()

await product_files.apply(archive_bytes, committed["commit_sha"])
await products.update(product.id, {
    "active_revision": committed["commit_sha"],
    "head_revision": committed["commit_sha"],
})

initialFiles, err := productFiles.BuildInitial(ctx, product.ID)
if err != nil {
	return err
}

change, err := repo.CreateCommit(storage.CommitOptions{
	TargetBranch:  "main",
	CommitMessage: "Create product definition",
	Author:        storage.CommitSignature{Name: "Product Service", Email: "product-service@example.com"},
})
if err != nil {
	return err
}

for path, contents := range initialFiles {
	change = change.AddFileFromString(path, contents, nil)
}

committed, err := change.Send(ctx)
if err != nil {
	return err
}
archive, err := repo.ArchiveStream(ctx, storage.ArchiveOptions{Ref: committed.CommitSHA})
if err != nil {
	return err
}
defer archive.Body.Close()

if err := productFiles.Apply(ctx, archive.Body, committed.CommitSHA); err != nil {
	return err
}
err = products.Update(ctx, product.ID, ProductUpdate{
	ActiveRevision: committed.CommitSHA,
	HeadRevision:   committed.CommitSHA,
})

Update activeRevision only after the apply step succeeds.

Validate and save a user edit

Build the complete file set that would result from the edit. Validate all files before you save any of them. If validation fails, return the errors and keep the active revision unchanged.

import { RefUpdateError } from '@pierre/storage';

const current = await products.find(product.id);
const candidateFiles = await productFiles.buildCandidate(current, submittedEdit);

let change = repo.createCommit({
  targetBranch: 'main',
  expectedHeadSha: current.headRevision,
  commitMessage: `Update ${current.name}`,
  author: { name: editor.name, email: editor.email },
});

for (const [path, contents] of Object.entries(candidateFiles)) {
  change = change.addFileFromString(path, contents);
}

for (const path of productFiles.deletedPaths(current.files, candidateFiles)) {
  change = change.deletePath(path);
}

let committed;

try {
  committed = await change.send();
} catch (error) {
  if (error instanceof RefUpdateError) {
    if (error.reason === 'conflict') {
      return { ok: false, reason: 'conflict' };
    }
    if (error.reason === 'precondition_failed') {
      return { ok: true, reason: 'no_changes' };
    }
  }

  throw error;
}

from pierre_storage import RefUpdateError

current = await products.find(product.id)
candidate_files = await product_files.build_candidate(current, submitted_edit)

change = repo.create_commit(
    target_branch="main",
    expected_head_sha=current.head_revision,
    commit_message=f"Update {current.name}",
    author={"name": editor.name, "email": editor.email},
)

for path, contents in candidate_files.items():
    change = change.add_file_from_string(path, contents)

for path in product_files.deleted_paths(current.files, candidate_files):
    change = change.delete_path(path)

try:
    committed = await change.send()
except RefUpdateError as error:
    if error.reason == "conflict":
        return {"ok": False, "reason": "conflict"}
    if error.reason == "precondition_failed":
        return {"ok": True, "reason": "no_changes"}
    raise

current, err := products.Find(ctx, product.ID)
if err != nil {
	return EditResult{}, err
}
candidateFiles, err := productFiles.BuildCandidate(ctx, current, submittedEdit)
if err != nil {
	return EditResult{}, err
}

change, err := repo.CreateCommit(storage.CommitOptions{
	TargetBranch:    "main",
	ExpectedHeadSHA: current.HeadRevision,
	CommitMessage:   fmt.Sprintf("Update %s", current.Name),
	Author:          storage.CommitSignature{Name: editor.Name, Email: editor.Email},
})
if err != nil {
	return EditResult{}, err
}

for path, contents := range candidateFiles {
	change = change.AddFileFromString(path, contents, nil)
}
for _, path := range productFiles.DeletedPaths(current.Files, candidateFiles) {
	change = change.DeletePath(path)
}

committed, err := change.Send(ctx)
if err != nil {
	var refErr *storage.RefUpdateError
	if errors.As(err, &refErr) {
		switch refErr.Reason {
		case storage.RefUpdateReasonConflict:
			return EditResult{OK: false, Reason: "conflict"}, nil
		case storage.RefUpdateReasonPreconditionFailed:
			return EditResult{OK: true, Reason: "no_changes"}, nil
		}
	}
	return EditResult{}, err
}

A conflict means that another editor saved first. Reload the current files and ask the editor to resolve the conflict. Do not save the old file set again without review. An identical candidate file set returns precondition_failed; treat it as success with no new revision. After a timeout, the commit can still exist. Do not resend the same request. Read the current head again. Rebuild the candidate file set from the current product state. Send a new commit with the new head as expectedHeadSha.

Apply the saved version

After a successful save, read the complete file set by its commit SHA. Apply only those files. Mark the commit as active only after the apply step succeeds.

const archive = await repo.getArchiveStream({ ref: committed.commitSha });

try {
  await productFiles.apply(archive.body!, committed.commitSha);
  await products.update(product.id, {
    activeRevision: committed.commitSha,
    headRevision: committed.commitSha,
  });
} catch (error) {
  await products.update(product.id, { headRevision: committed.commitSha });
  throw error;
}

archive = await repo.get_archive_stream(ref=committed["commit_sha"])

try:
    archive_bytes = await archive.aread()
    await product_files.apply(archive_bytes, committed["commit_sha"])
    await products.update(product.id, {
        "active_revision": committed["commit_sha"],
        "head_revision": committed["commit_sha"],
    })
except Exception:
    await products.update(product.id, {"head_revision": committed["commit_sha"]})
    raise

archive, err := repo.ArchiveStream(ctx, storage.ArchiveOptions{Ref: committed.CommitSHA})
if err != nil {
	return err
}

if err := productFiles.Apply(ctx, archive.Body, committed.CommitSHA); err != nil {
	archive.Body.Close()
	if updateErr := products.Update(ctx, product.ID, ProductUpdate{
		HeadRevision: committed.CommitSHA,
	}); updateErr != nil {
		return updateErr
	}
	return err
}
archive.Body.Close()

err = products.Update(ctx, product.ID, ProductUpdate{
	ActiveRevision: committed.CommitSHA,
	HeadRevision:   committed.CommitSHA,
})

Do not apply files that you have not saved. If the apply step fails, keep the prior active revision. Fix the apply service and retry the same commit SHA.

Show history and undo a change

Keep repository details behind your product interface. Use listCommits and getCommitDiff to show who changed the product and what changed.

const history = await repo.listCommits({ branch: 'main', limit: 20 });
const selected = history.commits[0];
const diff = await repo.getCommitDiff({ sha: selected.sha });

history = await repo.list_commits(branch="main", limit=20)
selected = history["commits"][0]
diff = await repo.get_commit_diff(sha=selected["sha"])

history, err := repo.ListCommits(ctx, storage.ListCommitsOptions{
	Branch: "main",
	Limit:  20,
})
if err != nil {
	return err
}
selected := history.Commits[0]
diff, err := repo.GetCommitDiff(ctx, storage.GetCommitDiffOptions{SHA: selected.SHA})

Use restoreCommit to create a new commit from an earlier version. Apply and record the new commit, not the old commit that supplied its files.

const restored = await repo.restoreCommit({
  targetBranch: 'main',
  expectedHeadSha: current.headRevision,
  targetCommitSha: selectedSafeRevision,
  commitMessage: `Restore ${selectedSafeRevision.slice(0, 7)}`,
  author: { name: editor.name, email: editor.email },
});

const archive = await repo.getArchiveStream({ ref: restored.commitSha });

try {
  await productFiles.apply(archive.body!, restored.commitSha);
  await products.update(product.id, {
    activeRevision: restored.commitSha,
    headRevision: restored.commitSha,
  });
} catch (error) {
  await products.update(product.id, { headRevision: restored.commitSha });
  throw error;
}

restored = await repo.restore_commit(
    target_branch="main",
    expected_head_sha=current.head_revision,
    target_commit_sha=selected_safe_revision,
    commit_message=f"Restore {selected_safe_revision[:7]}",
    author={"name": editor.name, "email": editor.email},
)

archive = await repo.get_archive_stream(ref=restored["commit_sha"])

try:
    archive_bytes = await archive.aread()
    await product_files.apply(archive_bytes, restored["commit_sha"])
    await products.update(product.id, {
        "active_revision": restored["commit_sha"],
        "head_revision": restored["commit_sha"],
    })
except Exception:
    await products.update(product.id, {"head_revision": restored["commit_sha"]})
    raise

restored, err := repo.RestoreCommit(ctx, storage.RestoreCommitOptions{
	TargetBranch:    "main",
	ExpectedHeadSHA: current.HeadRevision,
	TargetCommitSHA: selectedSafeRevision,
	CommitMessage:   fmt.Sprintf("Restore %s", selectedSafeRevision[:7]),
	Author:          storage.CommitSignature{Name: editor.Name, Email: editor.Email},
})
if err != nil {
	return err
}

archive, err := repo.ArchiveStream(ctx, storage.ArchiveOptions{Ref: restored.CommitSHA})
if err != nil {
	return err
}
defer archive.Body.Close()
if err := productFiles.Apply(ctx, archive.Body, restored.CommitSHA); err != nil {
	if updateErr := products.Update(ctx, product.ID, ProductUpdate{
		HeadRevision: restored.CommitSHA,
	}); updateErr != nil {
		return updateErr
	}
	return err
}
err = products.Update(ctx, product.ID, ProductUpdate{
	ActiveRevision: restored.CommitSHA,
	HeadRevision:   restored.CommitSHA,
})

Use the same failure rule for an undo. If the apply step fails, record the restored commit as the repository head and keep the prior active revision.

Limit service access

Keep the organization private key on your server or in a secret manager. Give each product service a temporary token for one managed repository. Grant only the permissions that the service needs. Use a separate repo:write token when the provisioning service creates a managed repository. See Authentication for token details. Use Load Agent Memory when an agent reads and updates selected memory files without human approval.

Getting Started

Platform

Workflows

Libraries

API Reference

Provision the managed repository

Create the first active revision

Validate and save a user edit

Apply the saved version

Show history and undo a change

Limit service access

​Provision the managed repository

​Create the first active revision

​Validate and save a user edit

​Apply the saved version

​Show history and undo a change

​Limit service access

​Related workflow

Provision the managed repository

Create the first active revision

Validate and save a user edit

Apply the saved version

Show history and undo a change

Limit service access

Related workflow