@lightward/mechanic-cli 0.1.0

package/dist/github-workflows.js

@@ -0,0 +1,293 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+const CLI_PACKAGE_SPEC = `${packageJson.name || "@lightward/mechanic-cli"}@${packageJson.version || "latest"}`;
+function withTrailingNewline(lines) {
+    return `${lines.join("\n")}\n`;
+}
+function validateWorkflow() {
+    return withTrailingNewline([
+        "name: Validate Mechanic tasks",
+        "",
+        "on:",
+        "  pull_request:",
+        "  workflow_dispatch:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "",
+        "jobs:",
+        "  validate:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - name: Check out repository",
+        "        uses: actions/checkout@v5",
+        "",
+        "      - name: Set up Node",
+        "        uses: actions/setup-node@v6",
+        "        with:",
+        "          node-version: 22",
+        "",
+        "      - name: Install Mechanic CLI",
+        `        run: npm install -g ${CLI_PACKAGE_SPEC}`,
+        "",
+        "      - name: Validate task files",
+        "        run: mechanic tasks validate tasks/",
+    ]);
+}
+function deployWorkflow() {
+    return withTrailingNewline([
+        "name: Deploy Mechanic tasks",
+        "",
+        "on:",
+        "  workflow_dispatch:",
+        "    inputs:",
+        "      task_path:",
+        '        description: "Task file to deploy. Leave blank only when deploy_all is true."',
+        "        required: false",
+        "        type: string",
+        "      deploy_all:",
+        '        description: "Deploy every task JSON file."',
+        "        required: true",
+        "        default: false",
+        "        type: boolean",
+        "      mode:",
+        '        description: "Run a dry-run plan or deploy after the plan succeeds."',
+        "        required: true",
+        "        default: dry-run",
+        "        type: choice",
+        "        options:",
+        "          - dry-run",
+        "          - deploy",
+        "",
+        "concurrency:",
+        "  group: mechanic-deploy-production",
+        "  cancel-in-progress: false",
+        "",
+        "jobs:",
+        "  plan:",
+        "    permissions:",
+        "      contents: read",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - name: Check out repository",
+        "        uses: actions/checkout@v5",
+        "",
+        "      - name: Set up Node",
+        "        uses: actions/setup-node@v6",
+        "        with:",
+        "          node-version: 22",
+        "",
+        "      - name: Install Mechanic CLI",
+        `        run: npm install -g ${CLI_PACKAGE_SPEC}`,
+        "",
+        "      - name: Validate task selection",
+        "        env:",
+        "          TASK_PATH: ${{ inputs.task_path }}",
+        "          DEPLOY_ALL: ${{ inputs.deploy_all }}",
+        "        shell: bash",
+        "        run: |",
+        '          if [[ -z "$TASK_PATH" && "$DEPLOY_ALL" != "true" ]]; then',
+        '            echo "Set task_path or deploy_all=true." >&2',
+        "            exit 1",
+        "          fi",
+        "",
+        '          if [[ -n "$TASK_PATH" && "$DEPLOY_ALL" == "true" ]]; then',
+        '            echo "Use task_path or deploy_all=true, not both." >&2',
+        "            exit 1",
+        "          fi",
+        "",
+        "      - name: Validate task files",
+        "        run: mechanic tasks validate tasks/",
+        "",
+        "      - name: Dry-run deploy plan",
+        "        env:",
+        "          MECHANIC_API_TOKEN: ${{ secrets.MECHANIC_API_TOKEN }}",
+        "          TASK_PATH: ${{ inputs.task_path }}",
+        "          DEPLOY_ALL: ${{ inputs.deploy_all }}",
+        "        shell: bash",
+        "        run: |",
+        '          if [[ "$DEPLOY_ALL" == "true" ]]; then',
+        "            mechanic tasks publish --all --dry-run",
+        "          else",
+        '            mechanic tasks publish "$TASK_PATH" --dry-run',
+        "          fi",
+        "",
+        "  deploy:",
+        "    if: ${{ inputs.mode == 'deploy' }}",
+        "    needs: plan",
+        "    permissions:",
+        "      contents: write",
+        "      pull-requests: write",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - name: Check out repository",
+        "        uses: actions/checkout@v5",
+        "",
+        "      - name: Set up Node",
+        "        uses: actions/setup-node@v6",
+        "        with:",
+        "          node-version: 22",
+        "",
+        "      - name: Install Mechanic CLI",
+        `        run: npm install -g ${CLI_PACKAGE_SPEC}`,
+        "",
+        "      - name: Deploy to Mechanic",
+        "        env:",
+        "          MECHANIC_API_TOKEN: ${{ secrets.MECHANIC_API_TOKEN }}",
+        "          TASK_PATH: ${{ inputs.task_path }}",
+        "          DEPLOY_ALL: ${{ inputs.deploy_all }}",
+        "        shell: bash",
+        "        run: |",
+        '          if [[ "$DEPLOY_ALL" == "true" ]]; then',
+        "            mechanic tasks publish --all",
+        "          else",
+        '            mechanic tasks publish "$TASK_PATH"',
+        "          fi",
+        "",
+        "      - name: Open sync-state pull request",
+        "        env:",
+        "          GH_TOKEN: ${{ github.token }}",
+        "        shell: bash",
+        "        run: |",
+        '          if [[ -z "$(git status --porcelain -- mechanic.json .mechanic tasks)" ]]; then',
+        '            echo "No Mechanic sync-state changes found."',
+        "            exit 0",
+        "          fi",
+        "",
+        '          BRANCH="mechanic-sync/from-deploy"',
+        '          PR_TITLE="Sync Mechanic deploy state"',
+        '          PR_BODY_FILE="$(mktemp)"',
+        '          git add mechanic.json .mechanic tasks',
+        '          CHANGE_SUMMARY="$(git diff --cached --stat -- mechanic.json .mechanic tasks || true)"',
+        "          {",
+        '            echo "Updates local Mechanic task sync state after a GitHub deploy."',
+        "            echo",
+        '            echo "Merge this PR before the next GitHub deploy so .mechanic/links.json and task hashes stay current."',
+        "            echo",
+        '            echo "## Changed files"',
+        "            echo",
+        "            echo '```'",
+        '            echo "$CHANGE_SUMMARY"',
+        "            echo '```'",
+        '          } > "$PR_BODY_FILE"',
+        '          git config user.name "github-actions[bot]"',
+        '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+        '          git fetch origin "$BRANCH":"refs/remotes/origin/$BRANCH" || true',
+        '          git checkout -B "$BRANCH"',
+        '          git commit -m "Sync Mechanic deploy state"',
+        '          git push --force-with-lease origin "$BRANCH"',
+        "",
+        '          if gh pr view "$BRANCH" >/dev/null 2>&1; then',
+        '            gh pr edit "$BRANCH" --title "$PR_TITLE" --body-file "$PR_BODY_FILE"',
+        "          else",
+        '            gh pr create \\',
+        '              --title "$PR_TITLE" \\',
+        '              --body-file "$PR_BODY_FILE" \\',
+        '              --head "$BRANCH" \\',
+        '              --base "${{ github.event.repository.default_branch }}"',
+        "          fi",
+    ]);
+}
+function syncFromAppWorkflow() {
+    return withTrailingNewline([
+        "name: Pull Mechanic task updates from app",
+        "",
+        "on:",
+        "  workflow_dispatch:",
+        "",
+        "permissions:",
+        "  contents: write",
+        "  pull-requests: write",
+        "",
+        "concurrency:",
+        "  group: mechanic-sync-from-app",
+        "  cancel-in-progress: false",
+        "",
+        "jobs:",
+        "  sync:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - name: Check out repository",
+        "        uses: actions/checkout@v5",
+        "",
+        "      - name: Set up Node",
+        "        uses: actions/setup-node@v6",
+        "        with:",
+        "          node-version: 22",
+        "",
+        "      - name: Install Mechanic CLI",
+        `        run: npm install -g ${CLI_PACKAGE_SPEC}`,
+        "",
+        "      - name: Pull tasks from Mechanic",
+        "        env:",
+        "          MECHANIC_API_TOKEN: ${{ secrets.MECHANIC_API_TOKEN }}",
+        "        run: mechanic tasks pull --all --force",
+        "",
+        "      - name: Validate task files",
+        "        run: mechanic tasks validate tasks/",
+        "",
+        "      - name: Open update pull request",
+        "        env:",
+        "          GH_TOKEN: ${{ github.token }}",
+        "        shell: bash",
+        "        run: |",
+        '          if [[ -z "$(git status --porcelain -- mechanic.json .mechanic tasks)" ]]; then',
+        '            echo "No Mechanic changes found."',
+        "            exit 0",
+        "          fi",
+        "",
+        '          BRANCH="mechanic-sync/from-app"',
+        '          PR_TITLE="Pull Mechanic task updates from app"',
+        '          PR_BODY_FILE="$(mktemp)"',
+        '          git add mechanic.json .mechanic tasks',
+        '          CHANGE_SUMMARY="$(git diff --cached --stat -- mechanic.json .mechanic tasks || true)"',
+        "          {",
+        '            echo "Updates task files from Mechanic."',
+        "            echo",
+        '            echo "## Changed files"',
+        "            echo",
+        '            if [[ -n "$CHANGE_SUMMARY" ]]; then',
+        "              echo '```'",
+        '              echo "$CHANGE_SUMMARY"',
+        "              echo '```'",
+        "            else",
+        '              echo "No file summary available."',
+        "            fi",
+        "            echo",
+        '            echo "V1 does not prune local files or links for tasks deleted in Mechanic."',
+        '          } > "$PR_BODY_FILE"',
+        '          git config user.name "github-actions[bot]"',
+        '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+        '          git fetch origin "$BRANCH":"refs/remotes/origin/$BRANCH" || true',
+        '          git checkout -B "$BRANCH"',
+        '          git commit -m "Pull Mechanic task updates from app"',
+        '          git push --force-with-lease origin "$BRANCH"',
+        "",
+        '          if gh pr view "$BRANCH" >/dev/null 2>&1; then',
+        '            gh pr edit "$BRANCH" --title "$PR_TITLE" --body-file "$PR_BODY_FILE"',
+        "          else",
+        '            gh pr create \\',
+        '              --title "$PR_TITLE" \\',
+        '              --body-file "$PR_BODY_FILE" \\',
+        '              --head "$BRANCH" \\',
+        '              --base "${{ github.event.repository.default_branch }}"',
+        "          fi",
+    ]);
+}
+export function githubWorkflowFiles() {
+    return [
+        {
+            path: ".github/workflows/mechanic-validate.yml",
+            contents: validateWorkflow(),
+        },
+        {
+            path: ".github/workflows/mechanic-deploy.yml",
+            contents: deployWorkflow(),
+        },
+        {
+            path: ".github/workflows/mechanic-sync-from-app.yml",
+            contents: syncFromAppWorkflow(),
+        },
+    ];
+}

package/dist/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function contentHash(value: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD"}

package/dist/hash.js

@@ -0,0 +1,5 @@
+import crypto from "node:crypto";
+import { sortValue } from "./json.js";
+export function contentHash(value) {
+    return crypto.createHash("sha256").update(JSON.stringify(sortValue(value))).digest("hex");
+}

package/dist/json.d.ts

@@ -0,0 +1,4 @@
+export declare function sortValue<T>(value: T): T;
+export declare function stableStringify(value: unknown): string;
+export declare function parseJson(contents: string, source: string): unknown;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAoBxC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOnE"}

package/dist/json.js

@@ -0,0 +1,30 @@
+import { CliError } from "./errors.js";
+export function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortValue(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.keys(value)
+            .sort()
+            .reduce((memo, key) => {
+            const nextValue = value[key];
+            if (nextValue !== undefined) {
+                memo[key] = sortValue(nextValue);
+            }
+            return memo;
+        }, {});
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortValue(value), null, 2);
+}
+export function parseJson(contents, source) {
+    try {
+        return JSON.parse(contents);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Invalid JSON in ${source}: ${message}`);
+    }
+}

package/dist/tasks.d.ts

@@ -0,0 +1,48 @@
+import type { JsonObject, LinkEntry, Project, TaskEnvelope } from "./types.js";
+export type ResolvedTaskSelector = {
+    input: string;
+    source: "file" | "helper" | "linked_remote_id" | "slug" | "remote_id";
+    slug?: string;
+    file?: string;
+    helperDir?: string;
+    link?: LinkEntry | null;
+    remoteId?: string;
+};
+type ResolveTaskSelectorOptions = {
+    allowHelperDir?: boolean;
+    allowRemoteId?: boolean;
+};
+export declare function taskSlug(input: string): string;
+export declare function taskFiles(project: Project): Promise<string[]>;
+export declare function slugFromTaskFile(filePath: string): string;
+export declare function taskPath(project: Project, slug: string): string;
+export declare function displayTaskPath(project: Project, filePath: string): string;
+export declare function readTaskFile(filePath: string): Promise<JsonObject>;
+export declare function readRawTaskFile(filePath: string): Promise<JsonObject>;
+export declare function writeTaskFilePath(filePath: string, task: JsonObject): Promise<string>;
+export declare function refreshHelperDirForTaskFile(filePath: string): Promise<void>;
+export declare function writeTaskFilePathAndRefreshHelper(filePath: string, task: JsonObject): Promise<string>;
+export declare function writeTaskFile(project: Project, slug: string, task: JsonObject, force?: boolean): Promise<string>;
+export declare function resolveTaskSelector(project: Project, input: string, options?: ResolveTaskSelectorOptions): Promise<ResolvedTaskSelector>;
+export declare function selectedTaskFiles(project: Project, input: string | undefined, all: boolean): Promise<string[]>;
+export declare function remoteChangedSinceLastPull(link: LinkEntry, remote: Pick<TaskEnvelope, "content_hash">): boolean;
+export declare function remoteChangedSinceLastPullDetails(force?: boolean): string;
+export declare function remoteChangedSinceLastPullMessage(relativeFile: string, remoteId: string): string;
+export declare function taskForPush(task: JsonObject): JsonObject;
+export declare function nextAvailableSlug(project: Project, baseSlug: string): Promise<string>;
+export declare function taskFromHelperDir(dirPath: string): Promise<JsonObject>;
+export declare function helperDirForTaskFile(filePath: string): string | null;
+export declare function unbundledHelperDirForTaskFile(filePath: string, task: JsonObject): Promise<string | null>;
+export declare function rawTaskFromHelperDir(dirPath: string): Promise<JsonObject>;
+export declare function unbundleTask(filePath: string, outDir: string): Promise<void>;
+export declare function bundleTask(dirPath: string, outFile: string): Promise<void>;
+export type ValidationResult = {
+    ok: boolean;
+    source: string;
+    errors: string[];
+};
+export declare function validateTask(task: JsonObject, source: string): ValidationResult;
+export declare function validateTaskForPush(task: JsonObject, source: string): ValidationResult;
+export declare function diffTasks(local: JsonObject, remote: JsonObject): string | null;
+export {};
+//# sourceMappingURL=tasks.d.ts.map

package/dist/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../src/tasks.ts"],"names":[],"mappings":"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"}