Read and edit saved local files by SHA-256

Use Altifigence CLI 0.1.9 on Linux to work with the saved files of a local project without opening the IDE. Each replacement names the SHA-256 of the content you read, and the command refuses it when the saved file no longer has that SHA-256.

Check the project

Use an absolute path to your local project. This example uses $HOME/alti-projects/demo-project. Run the commands as your ordinary user.

set -euo pipefail
PROJECT="$(cd "$HOME/alti-projects/demo-project" && pwd -P)"
WORK="$(mktemp -d)"
alti ide workspace health --project "$PROJECT" > "$WORK/health.json"
jq '{ok, git}' "$WORK/health.json"

health first completes any pending file transaction, then reports the project. Require exit status 0 and ok equal to true. name is the project folder name and git tells whether the project has a .git folder.

List and read files

alti ide workspace files --project "$PROJECT" --limit 100 > "$WORK/files.json"
jq '{total, truncated, first: .files[:5]}' "$WORK/files.json"

files lists saved files as sorted paths relative to the project. total counts all listed files and truncated is true when total exceeds --limit. The default limit is 500 and the maximum is 20000. Folders such as .git, .alti, .altifigence, node_modules, target and dist are left out.

Read one saved UTF-8 text file. These examples use notes/review.txt:

alti ide workspace read --project "$PROJECT" notes/review.txt > "$WORK/review.json"
jq '{path, encoding, sha256}' "$WORK/review.json"

The result has path, encoding (utf-8), sha256 and content. sha256 is the lowercase hexadecimal SHA-256 of the saved content. Files up to 4194304 bytes can be read.

Replace one file

Write the new content to a file, then pass the sha256 you read as --expected-sha256:

printf 'Third review\n' > "$WORK/review.txt"
alti ide workspace write --project "$PROJECT" notes/review.txt \
  --expected-sha256 "$(jq -r .sha256 "$WORK/review.json")" \
  --content "$WORK/review.txt" > "$WORK/write.receipt.json"
jq '{outcome}' "$WORK/write.receipt.json"

Require exit status 0 and outcome equal to committed:

{
  "outcome": "committed"
}

The receipt also has transactionId, generation, recoveryStatus and files, where each entry has path, beforeSha256 and afterSha256. write replaces an existing file. --content - reads the new content from standard input. Keep the content within 4194304 bytes.

Edit several files together

Read each file, then prepare a JSON array with one path, expected_sha256 and content entry per file:

alti ide workspace read --project "$PROJECT" notes/review.txt > "$WORK/review.json"
alti ide workspace read --project "$PROJECT" notes/todo.txt > "$WORK/todo.json"
jq -s '[
  {path: .[0].path, expected_sha256: .[0].sha256, content: "Fourth review\n"},
  {path: .[1].path, expected_sha256: .[1].sha256, content: "Check the review\n"}
]' "$WORK/review.json" "$WORK/todo.json" > "$WORK/edit.json"
alti ide workspace edit --project "$PROJECT" --request "$WORK/edit.json" \
  > "$WORK/edit.receipt.json"
jq '{outcome, files: [.files[].path]}' "$WORK/edit.receipt.json"

After exit status 0, the selected receipt fields are:

{
  "outcome": "committed",
  "files": [
    "notes/review.txt",
    "notes/todo.txt"
  ]
}

edit checks every entry before it changes any file, and applies the replacements as one transaction. Use 1 to 64 entries, one entry per path, each with new content. Keep each file within 4194304 bytes and the original and new content of all entries within 16777216 bytes.

Recover from a rejected edit

When the workspace engine rejects a write or edit request, the command exits with status 1 and writes an altifigence.ide-workspace-error.v1 object with a message to standard error. The CLI reports oversized input or an edit request whose JSON is not an array on standard error with the prefix error: and exits with status 1. For each message below, no file is changed.

For workspace edit original digest mismatch: notes/review.txt, the file changed after you read it. Read it again, review its current content, and repeat the replacement with the new sha256.

For workspace edit has no content change: notes/review.txt, the new content equals the saved content. Remove that entry or change its content.

For workspace edit transaction contains a duplicate path, combine the entries for that path into one entry with the final content.

For workspace edit SHA-256 digest must be 64 lowercase hexadecimal characters, copy the sha256 value from read unchanged.

For workspace path is outside the editable file surface, use a path relative to the project from the files listing, without . or .. segments.

For workspace exceeds 20000 files; narrow the project from files, open a smaller project folder.

Create, replace and delete local files