dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli/commands/project-git.js

@@ -2,6 +2,7 @@ import { validateGitReferencePath, } from "../../utils/git-reference.js";
 import { sanitizeErrorSecrets, sanitizeSecrets, } from "../../utils/secret-sanitize.js";
 import { num, parseBooleanOption, requiredStringFlag, } from "../coerce.js";
 import { CommandResultFailure, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 /** DSS names the default remote `origin`; the remote flag falls back to it. */
 const DEFAULT_REMOTE = "origin";
@@ -69,53 +70,53 @@ function libraryPassword(flags) {
         throw new UsageError("--password-env requires the name of an environment variable holding the password.", "invalid_flag_value", "Pass --password-env DSS_GIT_LIBRARY_PASSWORD, never the password itself.", { flag: "--password-env", });
     }
     const name = raw.trim();
+    // oxlint-disable-next-line dss/no-direct-process-env -- --password-env names the variable to read; must work under DATAIKU_DISABLE_ENV
     const value = process.env[name];
     if (value === undefined || value === "") {
         throw new UsageError(`Environment variable ${name} is not set or is empty.`, "missing_required_flag", "--password-env names the environment variable that holds the Git repository password; export that variable before running the command.", { flag: "--password-env", env: name, });
     }
     return value;
 }
-const STATUS_USAGE = "dss project-git status --project-key KEY";
-const GET_REMOTE_USAGE = "dss project-git get-remote --project-key KEY [--name NAME]";
-const SET_REMOTE_USAGE = "dss project-git set-remote --repository URL --project-key KEY [--name NAME]";
-const REMOVE_REMOTE_USAGE = "dss project-git remove-remote --project-key KEY [--name NAME]";
-const BRANCHES_USAGE = "dss project-git branches --project-key KEY [--remote]";
-const CREATE_BRANCH_USAGE = "dss project-git create-branch <name> --project-key KEY [--commit COMMIT] [--duplicate-project] [--target-project-key KEY] [--target-project-folder-id ID]";
-const DELETE_BRANCH_USAGE = "dss project-git delete-branch <name> --project-key KEY [--remote] [--delete-remotely] [--force-delete]";
-const CURRENT_BRANCH_USAGE = "dss project-git current-branch --project-key KEY";
-const TAGS_USAGE = "dss project-git tags --project-key KEY";
-const CREATE_TAG_USAGE = "dss project-git create-tag <name> --project-key KEY [--reference REF] [--message MESSAGE]";
-const DELETE_TAG_USAGE = "dss project-git delete-tag <name> --project-key KEY";
-const SWITCH_USAGE = "dss project-git switch <branch> --project-key KEY";
-const FETCH_USAGE = "dss project-git fetch --project-key KEY";
-const PULL_USAGE = "dss project-git pull --project-key KEY [--branch NAME]";
-const PUSH_USAGE = "dss project-git push --project-key KEY [--branch NAME]";
-const LOG_USAGE = "dss project-git log --project-key KEY [--path PATH] [--start-commit COMMIT] [--count N]";
-const DIFF_USAGE = "dss project-git diff --project-key KEY [--from COMMIT] [--to COMMIT]";
-const COMMIT_USAGE = "dss project-git commit --message MESSAGE --project-key KEY";
-const REVERT_TO_REVISION_USAGE = "dss project-git revert-to-revision <commit> --project-key KEY";
-const REVERT_COMMIT_USAGE = "dss project-git revert-commit <commit> --project-key KEY";
-const RESET_TO_HEAD_USAGE = "dss project-git reset-to-head --project-key KEY";
-const RESET_TO_UPSTREAM_USAGE = "dss project-git reset-to-upstream --project-key KEY";
-const DROP_AND_REBUILD_USAGE = "dss project-git drop-and-rebuild --i-know-what-i-am-doing --project-key KEY";
-const LIST_LIBRARIES_USAGE = "dss project-git list-libraries --project-key KEY";
-const ADD_LIBRARY_USAGE = "dss project-git add-library <target-path> --repository URL --checkout REF --project-key KEY [--path-in-repository PATH] [--login LOGIN] [--password-env ENV_NAME] [--no-add-to-python-path]";
-const SET_LIBRARY_USAGE = "dss project-git set-library <target-path> --repository URL --checkout REF --project-key KEY [--path-in-repository PATH] [--login LOGIN] [--password-env ENV_NAME]";
-const REMOVE_LIBRARY_USAGE = "dss project-git remove-library <target-path> --project-key KEY [--delete-directory]";
-const RESET_LIBRARY_USAGE = "dss project-git reset-library <target-path> --project-key KEY";
-const PUSH_LIBRARY_USAGE = "dss project-git push-library <target-path> --message MESSAGE --project-key KEY";
-const PUSH_ALL_LIBRARIES_USAGE = "dss project-git push-all-libraries --message MESSAGE --project-key KEY";
-const RESET_ALL_LIBRARIES_USAGE = "dss project-git reset-all-libraries --project-key KEY";
-const FUTURE_STATUS_USAGE = "dss project-git future-status <job-id> [--peek]";
-const FUTURE_WAIT_USAGE = "dss project-git future-wait <job-id> [--timeout MS] [--poll-interval MS]";
-const FUTURE_ABORT_USAGE = "dss project-git future-abort <job-id>";
-export const projectGitCommands = {
+const STATUS_USAGE = commandUsage("project-git", "status");
+const GET_REMOTE_USAGE = commandUsage("project-git", "get-remote");
+const SET_REMOTE_USAGE = commandUsage("project-git", "set-remote");
+const REMOVE_REMOTE_USAGE = commandUsage("project-git", "remove-remote");
+const BRANCHES_USAGE = commandUsage("project-git", "branches");
+const CREATE_BRANCH_USAGE = commandUsage("project-git", "create-branch");
+const DELETE_BRANCH_USAGE = commandUsage("project-git", "delete-branch");
+const CURRENT_BRANCH_USAGE = commandUsage("project-git", "current-branch");
+const TAGS_USAGE = commandUsage("project-git", "tags");
+const CREATE_TAG_USAGE = commandUsage("project-git", "create-tag");
+const DELETE_TAG_USAGE = commandUsage("project-git", "delete-tag");
+const SWITCH_USAGE = commandUsage("project-git", "switch");
+const FETCH_USAGE = commandUsage("project-git", "fetch");
+const PULL_USAGE = commandUsage("project-git", "pull");
+const PUSH_USAGE = commandUsage("project-git", "push");
+const LOG_USAGE = commandUsage("project-git", "log");
+const DIFF_USAGE = commandUsage("project-git", "diff");
+const COMMIT_USAGE = commandUsage("project-git", "commit");
+const REVERT_TO_REVISION_USAGE = commandUsage("project-git", "revert-to-revision");
+const REVERT_COMMIT_USAGE = commandUsage("project-git", "revert-commit");
+const RESET_TO_HEAD_USAGE = commandUsage("project-git", "reset-to-head");
+const RESET_TO_UPSTREAM_USAGE = commandUsage("project-git", "reset-to-upstream");
+const DROP_AND_REBUILD_USAGE = commandUsage("project-git", "drop-and-rebuild");
+const LIST_LIBRARIES_USAGE = commandUsage("project-git", "list-libraries");
+const ADD_LIBRARY_USAGE = commandUsage("project-git", "add-library");
+const SET_LIBRARY_USAGE = commandUsage("project-git", "set-library");
+const REMOVE_LIBRARY_USAGE = commandUsage("project-git", "remove-library");
+const RESET_LIBRARY_USAGE = commandUsage("project-git", "reset-library");
+const PUSH_LIBRARY_USAGE = commandUsage("project-git", "push-library");
+const PUSH_ALL_LIBRARIES_USAGE = commandUsage("project-git", "push-all-libraries");
+const RESET_ALL_LIBRARIES_USAGE = commandUsage("project-git", "reset-all-libraries");
+const FUTURE_STATUS_USAGE = commandUsage("project-git", "future-status");
+const FUTURE_WAIT_USAGE = commandUsage("project-git", "future-wait");
+const FUTURE_ABORT_USAGE = commandUsage("project-git", "future-abort");
+export const projectGitCommands = withUsage("project-git", {
     status: {
         handler: async (c, a, f) => {
             requireNoArgs(a, STATUS_USAGE);
             return sanitizeProjectGitOutput(await c.projectGit.status(requiredStringFlag(f, "project-key", STATUS_USAGE)));
         },
-        usage: STATUS_USAGE,
         description: "Get the project's Git working-copy status: current branch, remotes, tracking counts, and pending changes.",
         examples: ["dss project-git status --project-key MYPROJECT",],
     },
@@ -124,7 +125,6 @@ export const projectGitCommands = {
             requireNoArgs(a, GET_REMOTE_USAGE);
             return sanitizeProjectGitOutput(await c.projectGit.getRemote(requiredStringFlag(f, "project-key", GET_REMOTE_USAGE), optionalStringFlag(f, "name") ?? DEFAULT_REMOTE));
         },
-        usage: GET_REMOTE_USAGE,
         description: "Read one configured Git remote, origin by default. DSS answers an empty object when the remote is not configured.",
         examples: ["dss project-git get-remote --project-key MYPROJECT",],
     },
@@ -137,7 +137,6 @@ export const projectGitCommands = {
             });
             return assertGitActionSucceeded(result, "set-remote");
         },
-        usage: SET_REMOTE_USAGE,
         description: "Create or replace a Git remote. HTTP(S) URLs must not embed credentials; use an SSH remote or DSS-managed Git credentials instead.",
         examples: [
             "dss project-git set-remote --repository git@github.com:acme/analytics.git --project-key MYPROJECT",
@@ -150,7 +149,6 @@ export const projectGitCommands = {
             await c.projectGit.removeRemote(requiredStringFlag(f, "project-key", REMOVE_REMOTE_USAGE), name);
             return { removed: name, resource: "project-git-remote", };
         },
-        usage: REMOVE_REMOTE_USAGE,
         description: "Delete a Git remote from the project, origin by default.",
         examples: ["dss project-git remove-remote --name upstream --project-key MYPROJECT",],
     },
@@ -159,7 +157,6 @@ export const projectGitCommands = {
             requireNoArgs(a, BRANCHES_USAGE);
             return sanitizeProjectGitOutput(await c.projectGit.listBranches(requiredStringFlag(f, "project-key", BRANCHES_USAGE), parseBooleanOption(f["remote"], "--remote")));
         },
-        usage: BRANCHES_USAGE,
         description: "List local branch names, or remote-tracking branches with --remote.",
         examples: [
             "dss project-git branches --project-key MYPROJECT",
@@ -177,7 +174,6 @@ export const projectGitCommands = {
             });
             return assertGitActionSucceeded(result, "create-branch");
         },
-        usage: CREATE_BRANCH_USAGE,
         description: "Create a branch, optionally from a specific commit. With --duplicate-project DSS copies the project onto the new branch instead of switching this one.",
         examples: [
             "dss project-git create-branch feature/pricing --project-key MYPROJECT",
@@ -194,7 +190,6 @@ export const projectGitCommands = {
             });
             return assertGitActionSucceeded(result, "delete-branch");
         },
-        usage: DELETE_BRANCH_USAGE,
         description: "Delete a branch. --remote targets a remote-tracking branch, --delete-remotely also deletes it on the remote, and --force-delete drops unmerged commits.",
         examples: ["dss project-git delete-branch feature/pricing --project-key MYPROJECT",],
     },
@@ -204,7 +199,6 @@ export const projectGitCommands = {
             const branch = await c.projectGit.currentBranch(requiredStringFlag(f, "project-key", CURRENT_BRANCH_USAGE));
             return { branch, };
         },
-        usage: CURRENT_BRANCH_USAGE,
         description: "Get the project's current branch name, or null when DSS reports none.",
         examples: ["dss project-git current-branch --project-key MYPROJECT",],
     },
@@ -213,7 +207,6 @@ export const projectGitCommands = {
             requireNoArgs(a, TAGS_USAGE);
             return sanitizeProjectGitOutput(await c.projectGit.listTags(requiredStringFlag(f, "project-key", TAGS_USAGE)));
         },
-        usage: TAGS_USAGE,
         description: "List the project's Git tags.",
         examples: ["dss project-git tags --project-key MYPROJECT",],
     },
@@ -226,7 +219,6 @@ export const projectGitCommands = {
             });
             return assertGitActionSucceeded(result, "create-tag");
         },
-        usage: CREATE_TAG_USAGE,
         description: "Create a Git tag. --reference defaults to HEAD; passing --message creates an annotated tag.",
         examples: [
             'dss project-git create-tag v1.2.0 --message "Release 1.2.0" --project-key MYPROJECT',
@@ -238,7 +230,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.deleteTag(requiredStringFlag(f, "project-key", DELETE_TAG_USAGE), a[0]);
             return assertGitActionSucceeded(result, "delete-tag");
         },
-        usage: DELETE_TAG_USAGE,
         description: "Delete a Git tag from the project.",
         examples: ["dss project-git delete-tag v1.2.0 --project-key MYPROJECT",],
     },
@@ -248,7 +239,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.switchBranch(requiredStringFlag(f, "project-key", SWITCH_USAGE), a[0]);
             return assertGitActionSucceeded(result, "switch");
         },
-        usage: SWITCH_USAGE,
         description: "Switch the project to another branch. DSS rewrites the project's working copy in place.",
         examples: ["dss project-git switch main --project-key MYPROJECT",],
     },
@@ -258,7 +248,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.fetch(requiredStringFlag(f, "project-key", FETCH_USAGE));
             return assertGitActionSucceeded(result, "fetch");
         },
-        usage: FETCH_USAGE,
         description: "Fetch from the project's Git remote without changing the working copy.",
         examples: ["dss project-git fetch --project-key MYPROJECT",],
     },
@@ -268,7 +257,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.pull(requiredStringFlag(f, "project-key", PULL_USAGE), { branchName: optionalStringFlag(f, "branch"), });
             return assertGitActionSucceeded(result, "pull");
         },
-        usage: PULL_USAGE,
         description: "Pull with rebase. DSS exposes no merge variant of pull.",
         examples: ["dss project-git pull --project-key MYPROJECT",],
     },
@@ -278,7 +266,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.push(requiredStringFlag(f, "project-key", PUSH_USAGE), { branchName: optionalStringFlag(f, "branch"), });
             return assertGitActionSucceeded(result, "push");
         },
-        usage: PUSH_USAGE,
         description: "Push the project's committed changes to its Git remote.",
         examples: ["dss project-git push --project-key MYPROJECT",],
     },
@@ -291,7 +278,6 @@ export const projectGitCommands = {
                 count: num(f["count"], "--count"),
             }));
         },
-        usage: LOG_USAGE,
         description: "Read a page of the project's commit log. Paginate by passing the previous response's nextCommit as --start-commit.",
         examples: ["dss project-git log --count 20 --project-key MYPROJECT",],
     },
@@ -303,7 +289,6 @@ export const projectGitCommands = {
                 commitTo: optionalStringFlag(f, "to"),
             }));
         },
-        usage: DIFF_USAGE,
         description: "Diff the project between two commits. Omitting both bounds diffs the working copy against HEAD.",
         examples: ["dss project-git diff --from 4f1c2ab --to 9de77c1 --project-key MYPROJECT",],
     },
@@ -313,7 +298,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.commit(requiredStringFlag(f, "project-key", COMMIT_USAGE), { message: requiredStringFlag(f, "message", COMMIT_USAGE), });
             return assertGitActionSucceeded(result, "commit");
         },
-        usage: COMMIT_USAGE,
         description: "Commit the project. DSS stages untracked files before committing.",
         examples: [
             'dss project-git commit --message "Update pricing recipe" --project-key MYPROJECT',
@@ -325,7 +309,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.revertToRevision(requiredStringFlag(f, "project-key", REVERT_TO_REVISION_USAGE), a[0]);
             return assertGitActionSucceeded(result, "revert-to-revision");
         },
-        usage: REVERT_TO_REVISION_USAGE,
         description: "Restore the whole project to the state of a past commit, discarding everything after it in the working copy.",
         examples: ["dss project-git revert-to-revision 4f1c2ab --project-key MYPROJECT",],
     },
@@ -335,7 +318,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.revertCommit(requiredStringFlag(f, "project-key", REVERT_COMMIT_USAGE), a[0]);
             return assertGitActionSucceeded(result, "revert-commit");
         },
-        usage: REVERT_COMMIT_USAGE,
         description: "Revert a single commit while keeping the commits that follow it.",
         examples: ["dss project-git revert-commit 4f1c2ab --project-key MYPROJECT",],
     },
@@ -345,7 +327,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.resetToHead(requiredStringFlag(f, "project-key", RESET_TO_HEAD_USAGE));
             return assertGitActionSucceeded(result, "reset-to-head");
         },
-        usage: RESET_TO_HEAD_USAGE,
         description: "Hard reset the project to local HEAD, discarding uncommitted changes.",
         examples: ["dss project-git reset-to-head --project-key MYPROJECT",],
     },
@@ -355,7 +336,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.resetToUpstream(requiredStringFlag(f, "project-key", RESET_TO_UPSTREAM_USAGE));
             return assertGitActionSucceeded(result, "reset-to-upstream");
         },
-        usage: RESET_TO_UPSTREAM_USAGE,
         description: "Hard reset the project to its tracked upstream branch, discarding local commits.",
         examples: ["dss project-git reset-to-upstream --project-key MYPROJECT",],
     },
@@ -371,7 +351,6 @@ export const projectGitCommands = {
             const result = await c.projectGit.dropAndRebuild(projectKey, { confirmed: true, });
             return assertGitActionSucceeded(result, "drop-and-rebuild");
         },
-        usage: DROP_AND_REBUILD_USAGE,
         description: "Wipe the project's entire Git history and rebuild a fresh repository. Irreversible, so it requires --i-know-what-i-am-doing.",
         examples: [
             "dss project-git drop-and-rebuild --i-know-what-i-am-doing --project-key MYPROJECT",
@@ -382,7 +361,6 @@ export const projectGitCommands = {
             requireNoArgs(a, LIST_LIBRARIES_USAGE);
             return sanitizeProjectGitOutput(await c.projectGit.listLibraries(requiredStringFlag(f, "project-key", LIST_LIBRARIES_USAGE)));
         },
-        usage: LIST_LIBRARIES_USAGE,
         description: "List the external Git libraries attached to the project's code library.",
         examples: ["dss project-git list-libraries --project-key MYPROJECT",],
     },
@@ -401,7 +379,6 @@ export const projectGitCommands = {
                 password,
             }), password === undefined ? [] : [password,]);
         },
-        usage: ADD_LIBRARY_USAGE,
         description: "Attach an external Git repository to the project's code library and return the DSS future that clones it. The password is read only from the environment variable named by --password-env.",
         examples: [
             "dss project-git add-library shared-utils --repository git@github.com:acme/utils.git --checkout main --project-key MYPROJECT",
@@ -420,7 +397,6 @@ export const projectGitCommands = {
                 password,
             }), password === undefined ? [] : [password,]);
         },
-        usage: SET_LIBRARY_USAGE,
         description: "Update an attached library's repository, sub-path, or checkout. The password is read only from the environment variable named by --password-env.",
         examples: [
             "dss project-git set-library shared-utils --repository git@github.com:acme/utils.git --checkout v2 --path-in-repository python --project-key MYPROJECT",
@@ -435,7 +411,6 @@ export const projectGitCommands = {
             await c.projectGit.removeLibrary(requiredStringFlag(f, "project-key", REMOVE_LIBRARY_USAGE), targetPath, deleteDirectory);
             return { removed: targetPath, resource: "project-git-library", deleteDirectory, };
         },
-        usage: REMOVE_LIBRARY_USAGE,
         description: "Detach an external Git library. --delete-directory also removes its local directory from the project library.",
         examples: ["dss project-git remove-library shared-utils --project-key MYPROJECT",],
     },
@@ -444,7 +419,6 @@ export const projectGitCommands = {
             requireArgs(a, 1, RESET_LIBRARY_USAGE);
             return c.projectGit.resetLibrary(requiredStringFlag(f, "project-key", RESET_LIBRARY_USAGE), validateGitReferencePath(a[0]));
         },
-        usage: RESET_LIBRARY_USAGE,
         description: "Reset one attached library to its remote state, discarding local edits. Returns the DSS future that performs the reset.",
         examples: ["dss project-git reset-library shared-utils --project-key MYPROJECT",],
     },
@@ -453,7 +427,6 @@ export const projectGitCommands = {
             requireArgs(a, 1, PUSH_LIBRARY_USAGE);
             return c.projectGit.pushLibrary(requiredStringFlag(f, "project-key", PUSH_LIBRARY_USAGE), validateGitReferencePath(a[0]), requiredStringFlag(f, "message", PUSH_LIBRARY_USAGE));
         },
-        usage: PUSH_LIBRARY_USAGE,
         description: "Commit and push one attached library. Returns the DSS future that performs the push.",
         examples: [
             'dss project-git push-library shared-utils --message "Update helpers" --project-key MYPROJECT',
@@ -464,7 +437,6 @@ export const projectGitCommands = {
             requireNoArgs(a, PUSH_ALL_LIBRARIES_USAGE);
             return c.projectGit.pushAllLibraries(requiredStringFlag(f, "project-key", PUSH_ALL_LIBRARIES_USAGE), requiredStringFlag(f, "message", PUSH_ALL_LIBRARIES_USAGE));
         },
-        usage: PUSH_ALL_LIBRARIES_USAGE,
         description: "Commit and push every attached library. Returns the DSS future that performs the pushes.",
         examples: [
             'dss project-git push-all-libraries --message "Sync libraries" --project-key MYPROJECT',
@@ -475,7 +447,6 @@ export const projectGitCommands = {
             requireNoArgs(a, RESET_ALL_LIBRARIES_USAGE);
             return c.projectGit.resetAllLibraries(requiredStringFlag(f, "project-key", RESET_ALL_LIBRARIES_USAGE));
         },
-        usage: RESET_ALL_LIBRARIES_USAGE,
         description: "Reset every attached library to its remote state. Returns the DSS future that performs the resets.",
         examples: ["dss project-git reset-all-libraries --project-key MYPROJECT",],
     },
@@ -486,7 +457,6 @@ export const projectGitCommands = {
                 peek: parseBooleanOption(f["peek"], "--peek"),
             }));
         },
-        usage: FUTURE_STATUS_USAGE,
         description: "Get the state of a Git library future by job id. --peek leaves the result queued for a later read.",
         examples: ["dss project-git future-status FUTURE_ID --peek",],
     },
@@ -509,7 +479,6 @@ export const projectGitCommands = {
                 throw sanitizeProjectGitError(error);
             }
         },
-        usage: FUTURE_WAIT_USAGE,
         description: "Wait for a Git library future to finish and return its result.",
         examples: ["dss project-git future-wait FUTURE_ID --timeout 300000",],
     },
@@ -519,8 +488,7 @@ export const projectGitCommands = {
             await c.projectGit.abortFuture(a[0]);
             return { aborted: a[0], resource: "project-git-future", };
         },
-        usage: FUTURE_ABORT_USAGE,
         description: "Abort a running Git library future by job id.",
         examples: ["dss project-git future-abort FUTURE_ID",],
     },
-};
+});

package/dist/src/cli/commands/project-library.js

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
-import { encodeLibraryPath, EXPECT_SHA256_PATTERN, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../../resources/project-library.js";
+import { encodeLibraryPath, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../../resources/project-library.js";
+import { SHA256_HEX_PATTERN, } from "../../utils/stable-hash.js";
 import { numFlag, readStdinText, sha256Hex, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, planResult, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const PROJECT_LIBRARY_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
 const PUT_FLAG_ERROR_HINT = "Pass a 64-character SHA-256 hex digest (lowercase or uppercase).";
@@ -60,31 +62,29 @@ function expectSha256FromFlags(flags) {
     const value = flags["expect-sha256"];
     if (value === undefined || value === false)
         return undefined;
-    if (typeof value !== "string" || !EXPECT_SHA256_PATTERN.test(value)) {
+    if (typeof value !== "string" || !SHA256_HEX_PATTERN.test(value)) {
         throw new UsageError("--expect-sha256 must be a 64-character SHA-256 hex digest.", "validation_failed", PUT_FLAG_ERROR_HINT);
     }
     return value;
 }
-export const projectLibraryCommands = {
+export const projectLibraryCommands = withUsage("project-library", {
     list: {
         handler: (c, _a, f) => c.projectLibrary.listContents(f["project-key"]),
-        usage: "dss project-library list [--project-key KEY]",
         description: "List the project code library (lib/) contents.",
         examples: ["dss project-library list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss project-library get <path> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "get"));
             validateLibraryPath(a[0]);
             return c.projectLibrary.getFile(a[0], f["project-key"]);
         },
-        usage: "dss project-library get <path> [--project-key KEY]",
         description: "Print the text content of a project library file.",
         examples: ["dss project-library get python/mylib/utils.py",],
     },
     "get-bytes": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library get-bytes <path> --output PATH [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "get-bytes"));
             const out = f["output"];
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
@@ -92,13 +92,12 @@ export const projectLibraryCommands = {
             const written = await Bun.write(out, bytes, { createPath: false, });
             return { path: out, bytes: written, sha256: sha256BytesHex(bytes), };
         },
-        usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
         description: "Download a project library file's raw bytes to a local file.",
         examples: ["dss project-library get-bytes static/logo.png --output ./logo.png",],
     },
     "create-file": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library create-file <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "create-file"));
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
             if (executionMode(f).dryRun) {
@@ -118,13 +117,12 @@ export const projectLibraryCommands = {
             await c.projectLibrary.addFile(a[0], pk);
             return { created: a[0], };
         },
-        usage: "dss project-library create-file <path> [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create an empty file in the project library; refuses to overwrite an existing item.",
         examples: ["dss project-library create-file python/mylib/new.py --if-not-exists",],
     },
     "create-folder": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library create-folder <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "create-folder"));
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
             if (executionMode(f).dryRun) {
@@ -144,13 +142,12 @@ export const projectLibraryCommands = {
             await c.projectLibrary.addFolder(a[0], pk);
             return { created: a[0], };
         },
-        usage: "dss project-library create-folder <path> [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a folder in the project library; refuses to overwrite an existing item.",
         examples: ["dss project-library create-folder python/mylib --if-not-exists",],
     },
     put: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--expect-sha256 SHA256] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "put"));
             const pk = f["project-key"];
             const expectSha256 = expectSha256FromFlags(f);
             validateLibraryPath(a[0]);
@@ -175,7 +172,6 @@ export const projectLibraryCommands = {
                 ...(result.beforeSha256 !== undefined ? { beforeSha256: result.beforeSha256, } : {}),
             };
         },
-        usage: "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--expect-sha256 SHA256] [--dry-run] [--project-key KEY]",
         description: "Create or overwrite a project library file with text or binary content; reports the written byte count and sha256.",
         examples: [
             "dss project-library put python/mylib/utils.py --file ./utils.py",
@@ -184,7 +180,7 @@ export const projectLibraryCommands = {
     },
     diff: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library diff <path> (--content TEXT|--file PATH|--stdin) [--max-lines N] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "diff"));
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
             const maxLines = numFlag(f, ["max-lines",]);
@@ -195,7 +191,6 @@ export const projectLibraryCommands = {
                     : await readStdinText();
             return c.projectLibrary.diffFile(a[0], local, pk, maxLines !== undefined ? { maxLines, } : {});
         },
-        usage: "dss project-library diff <path> (--content TEXT|--file PATH|--stdin) [--max-lines N] [--project-key KEY]",
         description: "Diff a project library file against local content; capped unified text diff, binary files detected instead of dumped.",
         examples: [
             "dss project-library diff python/mylib/utils.py --file ./utils.py",
@@ -204,7 +199,7 @@ export const projectLibraryCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project-library delete <path> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("project-library", "delete"));
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
             if (executionMode(f).dryRun) {
@@ -217,13 +212,12 @@ export const projectLibraryCommands = {
             await c.projectLibrary.deleteFile(a[0], pk);
             return { deleted: a[0], };
         },
-        usage: "dss project-library delete <path> [--dry-run] [--project-key KEY]",
         description: "Delete a project library file or folder.",
         examples: ["dss project-library delete python/mylib/old.py",],
     },
     rename: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss project-library rename <path> <new-name> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("project-library", "rename"));
             const pk = f["project-key"];
             const validPath = validateLibraryPath(a[0]);
             const validName = validateLibraryName(a[1]);
@@ -238,13 +232,12 @@ export const projectLibraryCommands = {
             await c.projectLibrary.rename(validPath, validName, pk);
             return { renamed: validPath, to: validName, };
         },
-        usage: "dss project-library rename <path> <new-name> [--dry-run] [--project-key KEY]",
         description: "Rename a project library file or folder within its parent.",
         examples: ["dss project-library rename python/mylib/old.py new.py",],
     },
     move: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss project-library move <path> <destination-folder> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("project-library", "move"));
             const pk = f["project-key"];
             const validPath = validateLibraryPath(a[0]);
             const destination = validateLibraryDestinationPath(a[1]);
@@ -262,8 +255,7 @@ export const projectLibraryCommands = {
             await c.projectLibrary.move(validPath, destination, pk);
             return { moved: validPath, to: destination, };
         },
-        usage: "dss project-library move <path> <destination-folder> [--dry-run] [--project-key KEY]",
         description: "Move a project library file or folder into another folder.",
         examples: ["dss project-library move python/old.py python/mylib",],
     },
-};
+});