@stacksjs/buddy 0.70.163 → 0.70.164

package/dist/commands/docs/links.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "bun:test";
+import { extractLinks, isSkippableLink, resolveCandidates } from "./links";
+describe("docs link checker (stacksjs/stacks#2056)", () => {
+  describe("isSkippableLink", () => {
+    it("skips external, mail/tel, anchors, protocol-relative, and templated links", () => {
+      for (const target of ["https://x.com", "http://x.com", "mailto:a@b.c", "tel:123", "#section", "//cdn.example.com/x", "{{ url }}", "data:image/png;base64,AAAA", ""])
+        expect(isSkippableLink(target)).toBe(!0);
+    });
+    it("does not skip internal relative or absolute links", () => {
+      for (const target of ["./foo.md", "../bar/baz.md", "/guide/intro", "sibling.md"])
+        expect(isSkippableLink(target)).toBe(!1);
+    });
+  });
+  describe("extractLinks", () => {
+    it("extracts inline links with 1-based line numbers", () => {
+      expect(extractLinks(`intro
+
+see [a](./a.md) and [b](../b.md)
+`)).toEqual([
+        { target: "./a.md", line: 3 },
+        { target: "../b.md", line: 3 }
+      ]);
+    });
+    it("strips an optional link title", () => {
+      expect(extractLinks('[x](/guide/x "The X page")')).toEqual([{ target: "/guide/x", line: 1 }]);
+    });
+    it("ignores links inside fenced code blocks", () => {
+      expect(extractLinks("```md\n[x](./nope.md)\n```\n[y](./yes.md)\n")).toEqual([{ target: "./yes.md", line: 4 }]);
+    });
+    it("ignores links inside inline code spans", () => {
+      expect(extractLinks("use `[x](./nope.md)` but link [y](./yes.md)")).toEqual([{ target: "./yes.md", line: 1 }]);
+    });
+    it("ignores links inside HTML comments while preserving line numbers", () => {
+      expect(extractLinks(`line1
+<!-- ![x](./commented.png) -->
+real [y](./y.md)
+`)).toEqual([{ target: "./y.md", line: 3 }]);
+    });
+    it("handles a multi-line HTML comment", () => {
+      expect(extractLinks(`<!--
+[x](./a.md)
+-->
+[y](./b.md)
+`)).toEqual([{ target: "./b.md", line: 4 }]);
+    });
+  });
+  describe("resolveCandidates", () => {
+    const docsRoot = "/docs", fileDir = "/docs/guide/components";
+    it("resolves a relative link against the file directory", () => {
+      expect(resolveCandidates("./tabs.md", fileDir, docsRoot)).toEqual(["/docs/guide/components/tabs.md"]);
+    });
+    it("resolves an absolute link against the docs root", () => {
+      expect(resolveCandidates("/guide/intro.md", fileDir, docsRoot)).toEqual(["/docs/guide/intro.md"]);
+    });
+    it("offers .md and index.md candidates for an extensionless (clean-URL) link", () => {
+      expect(resolveCandidates("../intro", fileDir, docsRoot)).toEqual([
+        "/docs/guide/intro",
+        "/docs/guide/intro.md",
+        "/docs/guide/intro/index.md"
+      ]);
+    });
+    it("offers the .md source for an .html link", () => {
+      const candidates = resolveCandidates("./api.html", fileDir, docsRoot);
+      expect(candidates).toContain("/docs/guide/components/api.md");
+    });
+    it("strips the anchor before resolving", () => {
+      expect(resolveCandidates("./tabs.md#usage", fileDir, docsRoot)).toEqual(["/docs/guide/components/tabs.md"]);
+    });
+    it("returns no candidates for a pure anchor", () => {
+      expect(resolveCandidates("#usage", fileDir, docsRoot)).toEqual([]);
+    });
+  });
+});

package/dist/commands/docs.d.ts

@@ -0,0 +1,7 @@
+import type { CLI } from '@stacksjs/types';
+/**
+ * Framework-repo `buddy docs:*` commands wrapping the documentation-freshness
+ * tooling under `commands/docs/`: the generated buddy command reference,
+ * generated API artifacts (OpenAPI + types), and internal link checking.
+ */
+export declare function docs(buddy: CLI): void;

package/dist/commands/docs.js

@@ -0,0 +1,24 @@
+import { run as runArtifacts } from "./docs/generated-artifacts";
+import { run as runBuddyDocs } from "./docs/buddy-commands";
+import { run as runLinks } from "./docs/links";
+import { runTool } from "./run-tool";
+export function docs(buddy) {
+  buddy.command("docs:buddy", "Regenerate the buddy command reference doc").action(async () => {
+    await runTool(runBuddyDocs, "--write");
+  });
+  buddy.command("docs:buddy:check", "Verify the buddy command reference doc is current").action(async () => {
+    await runTool(runBuddyDocs, "--check");
+  });
+  buddy.command("docs:artifacts", "Regenerate the generated API artifacts (OpenAPI + types)").action(async () => {
+    await runTool(runArtifacts, "--write");
+  });
+  buddy.command("docs:artifacts:check", "Verify the generated API artifacts are current").action(async () => {
+    await runTool(runArtifacts, "--check");
+  });
+  buddy.command("docs:links", "Report internal documentation links").action(async () => {
+    await runTool(runLinks);
+  });
+  buddy.command("docs:links:check", "Verify internal documentation links resolve").action(async () => {
+    await runTool(runLinks, "--check");
+  });
+}

package/dist/commands/doctor.js

@@ -185,6 +185,14 @@ export function doctor(buddy) {
       const { config } = await import("@stacksjs/config");
       return `Driver: ${config.email?.default ?? "log"}`;
     });
+    {
+      const { ensureRuntimeDirectories, projectPath } = await import("@stacksjs/path"), leftover = ensureRuntimeDirectories().filter((entry) => !entry.cleared);
+      checks.push(leftover.length === 0 ? { name: "Runtime directories", status: "pass", message: "All under storage/" } : {
+        name: "Runtime directories",
+        status: "warn",
+        message: `Still in the project root: ${leftover.map((entry) => entry.legacy.slice(projectPath().length + 1)).join(", ")} \u2014 remove them so state stays under storage/`
+      });
+    }
     const hasAwsCreds = Boolean(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY), hasAwsRole = Boolean(process.env.AWS_PROFILE) || Boolean(process.env.AWS_ROLE_ARN);
     if (hasAwsCreds || hasAwsRole)
       checks.push({

package/dist/commands/env.d.ts

@@ -1,2 +1,16 @@
 import type { CLI } from '@stacksjs/types';
 export declare function env(buddy: CLI): void;
+/**
+ * Parses `KEY=value` assignments out of a dotenv file into a flat map.
+ *
+ * Deliberately tolerant of what real `.env` files contain: comments, blank
+ * lines, `export ` prefixes, quoted values, and - the case that matters here -
+ * dotenvx ciphertext, which wraps across many lines inside its quotes. A naive
+ * `split('\n')` treats each wrapped fragment as its own line and loses the key
+ * it belongs to.
+ *
+ * Values are returned raw (still encrypted, if they were). `env:check` only
+ * needs the key names and whether a value is non-empty, so nothing here has to
+ * decrypt - which also means it works without the private key present.
+ */
+export declare function parseEnvAssignments(content: string): Record<string, string>;

package/dist/commands/env.js

@@ -135,16 +135,14 @@ export function env(buddy) {
         message: "Found"
       });
       try {
-        const envContent = await storage.readTextFile(envPath), lines = String(envContent).split(`
-`).filter((line) => line.trim() && !line.startsWith("#")), varCount = lines.length;
+        const envContent = await storage.readTextFile(envPath), contentStr = typeof envContent === "string" ? envContent : envContent.data, values = parseEnvAssignments(contentStr), keys = Object.keys(values), varCount = keys.length;
         checks.push({
           name: "Environment variables",
           status: "pass",
           message: `${varCount} variables defined`
         });
-        if (lines.some((line) => line.startsWith("APP_KEY="))) {
-          const appKeyLine = lines.find((line) => line.startsWith("APP_KEY=")), eq = appKeyLine?.indexOf("=") ?? -1, appKeyValue = (eq >= 0 ? appKeyLine.slice(eq + 1) : "").trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
-          if (appKeyValue && appKeyValue.length > 0)
+        if ("APP_KEY" in values)
+          if ((values.APP_KEY ?? "").length > 0)
             checks.push({
               name: "APP_KEY",
               status: "pass",
@@ -156,13 +154,13 @@ export function env(buddy) {
               status: "warn",
               message: "Empty (run: buddy key:generate)"
             });
-        } else
+        else
           checks.push({
             name: "APP_KEY",
             status: "warn",
             message: "Not found (run: buddy key:generate)"
           });
-        const hasPublicKey = lines.some((line) => line.startsWith("DOTENV_PUBLIC_KEY=")), hasPrivateKey = lines.some((line) => line.startsWith("DOTENV_PRIVATE_KEY="));
+        const hasPublicKey = keys.some((key) => key.startsWith("DOTENV_PUBLIC_KEY")), hasPrivateKey = keys.some((key) => key.startsWith("DOTENV_PRIVATE_KEY")) || existsSync(resolve(process.cwd(), ".env.keys"));
         if (hasPublicKey && hasPrivateKey)
           checks.push({
             name: "Encryption keys",
@@ -181,6 +179,41 @@ export function env(buddy) {
             status: "warn",
             message: "Not configured (optional)"
           });
+        const declaredTenants = await resolveDeclaredTenants();
+        if (declaredTenants.tenants.length === 0)
+          checks.push({
+            name: "Tenant isolation",
+            status: "pass",
+            message: "No tenants declared (cloud.tenants)"
+          });
+        else {
+          const { foreignTenantKeys, partitionTenantEnv } = await import("@stacksjs/env"), foreign = foreignTenantKeys(partitionTenantEnv(values, declaredTenants)), isShipped = /^\.env\.[a-z]+$/.test(envFile), total = foreign.reduce((sum, entry) => sum + entry.keys.length, 0);
+          if (foreign.length === 0)
+            checks.push({
+              name: "Tenant isolation",
+              status: "pass",
+              message: `No foreign keys (checked ${declaredTenants.tenants.join(", ")})`
+            });
+          else if (!isShipped)
+            checks.push({
+              name: "Tenant isolation",
+              status: "pass",
+              message: `${total} archived key(s) \u2014 ${envFile} is local-only and never deployed`
+            });
+          else {
+            checks.push({
+              name: "Tenant isolation",
+              status: "warn",
+              message: `${total} key(s) belong to another tenant \u2014 move them to .env`
+            });
+            for (const { tenant, keys } of foreign)
+              checks.push({
+                name: `  ${tenant}`,
+                status: "warn",
+                message: keys.join(", ")
+              });
+          }
+        }
       } catch (error) {
         checks.push({
           name: `${envFile} content`,
@@ -244,3 +277,36 @@ export function env(buddy) {
   });
   onUnknownSubcommand(buddy, "env");
 }
+async function resolveDeclaredTenants() {
+  try {
+    const { config } = await import("@stacksjs/config"), cloud = config.cloud, app = config.app, tenants = Array.isArray(cloud?.tenants) ? cloud.tenants.filter((slug) => typeof slug === "string") : [];
+    return { self: app?.name, tenants };
+  } catch {
+    return { tenants: [] };
+  }
+}
+export function parseEnvAssignments(content) {
+  const values = {}, assignment = /^\s*(?:export\s+)?([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/i, lines = content.split(/\r?\n/);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith("#"))
+      continue;
+    const match = line.match(assignment);
+    if (!match)
+      continue;
+    const [, key, first] = match;
+    let raw = first.trim();
+    const quote = raw[0] === '"' || raw[0] === "'" ? raw[0] : void 0;
+    if (quote) {
+      raw = raw.slice(1);
+      while (!raw.endsWith(quote) && i + 1 < lines.length) {
+        i++;
+        raw += lines[i];
+      }
+      raw = raw.endsWith(quote) ? raw.slice(0, -1) : raw;
+    } else
+      raw = raw.replace(/\s+#.*$/, "").trim();
+    values[key] = raw;
+  }
+  return values;
+}

package/dist/commands/generate.js

@@ -96,7 +96,7 @@ export function generate(buddy) {
       process.exit(ExitCode.FatalError);
     }
   });
-  buddy.command("generate:core-symlink", "Generate core symlink. A shortcut for core developers.").action(async (options) => {
+  buddy.command("generate:core-symlink", "Symlink `.framework` -> storage/framework. A shortcut for core developers.").action(async (options) => {
     log.debug("Running `buddy core-symlink` ...", options);
     await generateCoreSymlink();
   });

package/dist/commands/index.d.ts

@@ -13,6 +13,7 @@ export * from './create';
 export * from './deploy';
 export * from './dev';
 export * from './dns';
+export * from './docs';
 export * from './doctor';
 export * from './domains';
 export * from './email';
@@ -34,6 +35,7 @@ export * from './phone';
 export * from './ports';
 export * from './prepublish';
 export * from './projects';
+export * from './protocol';
 export * from './publish';
 export * from './queue';
 export * from './release';

package/dist/commands/index.js

@@ -13,6 +13,7 @@ export * from "./create";
 export * from "./deploy";
 export * from "./dev";
 export * from "./dns";
+export * from "./docs";
 export * from "./doctor";
 export * from "./domains";
 export * from "./email";
@@ -34,6 +35,7 @@ export * from "./phone";
 export * from "./ports";
 export * from "./prepublish";
 export * from "./projects";
+export * from "./protocol";
 export * from "./publish";
 export * from "./queue";
 export * from "./release";

package/dist/commands/mail.js

@@ -17,7 +17,7 @@ export function sanitizeLineCount(value) {
   const count = Number.parseInt(value || "50", 10);
   return String(Number.isFinite(count) ? Math.min(5000, Math.max(1, count)) : 50);
 }
-function shellQuote(_value) {
+function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 async function resolveOperationalMailHost() {

package/dist/commands/migrate.js

@@ -3,7 +3,7 @@ import process from "node:process";
 import { confirm, intro, log, onUnknownSubcommand, outro, text } from "@stacksjs/cli";
 import { Action } from "@stacksjs/enums";
 import { hasTTY, isCI } from "@stacksjs/env";
-import { appPath, frameworkPath, projectPath } from "@stacksjs/path";
+import { appPath, frameworkPath, frameworkRuntimePath, projectPath } from "@stacksjs/path";
 import { ExitCode } from "@stacksjs/types";
 let _runAction;
 async function runAction(...args) {
@@ -12,7 +12,7 @@ async function runAction(...args) {
   return _runAction(...args);
 }
 function acquireMigrationLock() {
-  const lockDir = projectPath(".stacks"), lockFile = `${lockDir}/migrations.lock`;
+  const lockDir = frameworkRuntimePath(), lockFile = `${lockDir}/migrations.lock`;
   try {
     if (!existsSync(lockDir))
       mkdirSync(lockDir, { recursive: !0 });
@@ -36,7 +36,7 @@ function acquireMigrationLock() {
   }
 }
 function readMigrateMarker() {
-  const file = projectPath(".stacks/last-migrate-result.json");
+  const file = frameworkRuntimePath("last-migrate-result.json");
   if (!existsSync(file))
     return null;
   try {
@@ -235,7 +235,7 @@ export function migrate(buddy) {
       }
     const lock = acquireMigrationLock();
     if (!lock.acquired) {
-      log.syncError("Another migration is already running (.stacks/migrations.lock exists). Wait for it to finish, or remove the lockfile if it is stale.");
+      log.syncError("Another migration is already running (storage/framework/runtime/migrations.lock exists). Wait for it to finish, or remove the lockfile if it is stale.");
       process.exit(ExitCode.FatalError);
     }
     if (!await confirmDestructiveMigrations({ force: options.force, fromDb: options.fromDb, applyRenames })) {

package/dist/commands/protocol/craft-evidence.d.ts

@@ -0,0 +1,76 @@
+export declare function validateCraftEvidence(evidence: typeof craftEvidence): string[];
+export declare function run(): Promise<void>;
+export declare const craftEvidence: {
+  schemaVersion: 1;
+  status: 'source-verified-ci-retained';
+  source: {
+  repository: 'https://github.com/home-lang/craft';
+  version: '0.0.48';
+  tag: 'v0.0.48';
+  revision: 'bf75807669e3af6cfb4ae34724be5c613442aee2'
+};
+  issues: {
+  support: 'https://github.com/stacksjs/stacks/issues/2059';
+  signing: 'https://github.com/stacksjs/stacks/issues/2062';
+  lifecycle: 'https://github.com/stacksjs/stacks/issues/2063';
+  upstreamActions: 'https://github.com/home-lang/craft/issues/11';
+  dmgContention: 'https://github.com/home-lang/craft/issues/16'
+};
+  contracts: readonly [{
+  path: 'packages/typescript/src/package.ts';
+  sha256: 'a7522f8c79dbd50a0f3bbc113525fb46eb8d6d1bab711d434cae85dc892ccdc1'
+}, {
+  path: 'packages/typescript/src/package.test.ts';
+  sha256: '673338f3793e397a83590daf84815869b0698b4afe97eaad8039426418554b7a'
+}, {
+  path: 'scripts/native-lifecycle.ts';
+  sha256: 'a2c0af2c2165981ca7fbd31880adeec64db64fc305d4ca3efe62a11483b289b4'
+}, {
+  path: 'scripts/native-lifecycle-plan.ts';
+  sha256: 'ac8e8f101246e94c0c26fdcbf9202536426bf192a303606079273d9689e4e27d'
+}, {
+  path: 'scripts/native-lifecycle-plan.test.ts';
+  sha256: '5cc839b60f7c8e32716f29201b159af817f4ac40b2c7963131124b3ac5de0638'
+}, {
+  path: '.github/workflows/native-lifecycle.yml';
+  sha256: '493b614554f03dc669724ff31bd56ae8361851dd2a9b32ac37560d9c0bb1b85e'
+}, {
+  path: '.github/workflows/release.yml';
+  sha256: 'e3c7edd45841a7260fb4dfe810f0ff3f63f3117f7d0f4d14984e4dfb36b1f638'
+}];
+  lifecycleMatrix: readonly [{
+  runner: 'macos-15';
+  platform: 'darwin';
+  architecture: 'arm64';
+  formats: readonly ['dmg', 'pkg']
+}, {
+  runner: 'macos-15-intel';
+  platform: 'darwin';
+  architecture: 'x64';
+  formats: readonly ['dmg', 'pkg']
+}, {
+  runner: 'ubuntu-24.04';
+  platform: 'linux';
+  architecture: 'x64';
+  formats: readonly ['deb']
+}, {
+  runner: 'windows-2025';
+  platform: 'win32';
+  architecture: 'x64';
+  formats: readonly ['msi', 'zip']
+}];
+  lifecycleOperations: readonly ['install', 'launch', 'update', 'rollback', 'uninstall'];
+  stacksWorkflow: 'https://github.com/stacksjs/stacks/actions/workflows/desktop-lifecycle.yml';
+  release: {
+  sourceTagged: true;
+  githubRelease: null;
+  packagePublished: false;
+  signing: 'pending';
+  notarization: 'pending';
+  blockedBy: 'https://github.com/home-lang/craft/issues/11'
+};
+  verification: {
+  local: readonly ['bun test packages/typescript/src/package.test.ts scripts/native-lifecycle-plan.test.ts', 'bun run typecheck', 'bun .github/scripts/native-lifecycle.ts'];
+  retained: 'https://github.com/stacksjs/stacks/actions/runs/29890804159'
+}
+};

package/dist/commands/protocol/craft-evidence.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const root = resolve(import.meta.dir, "../../../../../../.."), outputPath = resolve(root, ".github/protocol/evidence/craft.json");
+export const craftEvidence = {
+  schemaVersion: 1,
+  status: "source-verified-ci-retained",
+  source: {
+    repository: "https://github.com/home-lang/craft",
+    version: "0.0.48",
+    tag: "v0.0.48",
+    revision: "bf75807669e3af6cfb4ae34724be5c613442aee2"
+  },
+  issues: {
+    support: "https://github.com/stacksjs/stacks/issues/2059",
+    signing: "https://github.com/stacksjs/stacks/issues/2062",
+    lifecycle: "https://github.com/stacksjs/stacks/issues/2063",
+    upstreamActions: "https://github.com/home-lang/craft/issues/11",
+    dmgContention: "https://github.com/home-lang/craft/issues/16"
+  },
+  contracts: [
+    { path: "packages/typescript/src/package.ts", sha256: "a7522f8c79dbd50a0f3bbc113525fb46eb8d6d1bab711d434cae85dc892ccdc1" },
+    { path: "packages/typescript/src/package.test.ts", sha256: "673338f3793e397a83590daf84815869b0698b4afe97eaad8039426418554b7a" },
+    { path: "scripts/native-lifecycle.ts", sha256: "a2c0af2c2165981ca7fbd31880adeec64db64fc305d4ca3efe62a11483b289b4" },
+    { path: "scripts/native-lifecycle-plan.ts", sha256: "ac8e8f101246e94c0c26fdcbf9202536426bf192a303606079273d9689e4e27d" },
+    { path: "scripts/native-lifecycle-plan.test.ts", sha256: "5cc839b60f7c8e32716f29201b159af817f4ac40b2c7963131124b3ac5de0638" },
+    { path: ".github/workflows/native-lifecycle.yml", sha256: "493b614554f03dc669724ff31bd56ae8361851dd2a9b32ac37560d9c0bb1b85e" },
+    { path: ".github/workflows/release.yml", sha256: "e3c7edd45841a7260fb4dfe810f0ff3f63f3117f7d0f4d14984e4dfb36b1f638" }
+  ],
+  lifecycleMatrix: [
+    { runner: "macos-15", platform: "darwin", architecture: "arm64", formats: ["dmg", "pkg"] },
+    { runner: "macos-15-intel", platform: "darwin", architecture: "x64", formats: ["dmg", "pkg"] },
+    { runner: "ubuntu-24.04", platform: "linux", architecture: "x64", formats: ["deb"] },
+    { runner: "windows-2025", platform: "win32", architecture: "x64", formats: ["msi", "zip"] }
+  ],
+  lifecycleOperations: ["install", "launch", "update", "rollback", "uninstall"],
+  stacksWorkflow: "https://github.com/stacksjs/stacks/actions/workflows/desktop-lifecycle.yml",
+  release: {
+    sourceTagged: !0,
+    githubRelease: null,
+    packagePublished: !1,
+    signing: "pending",
+    notarization: "pending",
+    blockedBy: "https://github.com/home-lang/craft/issues/11"
+  },
+  verification: {
+    local: ["bun test packages/typescript/src/package.test.ts scripts/native-lifecycle-plan.test.ts", "bun run typecheck", "bun .github/scripts/native-lifecycle.ts"],
+    retained: "https://github.com/stacksjs/stacks/actions/runs/29890804159"
+  }
+};
+export function validateCraftEvidence(evidence) {
+  const errors = [];
+  if (evidence.source.tag !== `v${evidence.source.version}`)
+    errors.push("Craft tag does not match its version");
+  if (!/^[a-f0-9]{40}$/.test(evidence.source.revision))
+    errors.push("Craft revision is not a full commit SHA");
+  if (evidence.contracts.length !== 7)
+    errors.push("all Craft packaging/release contracts must be pinned");
+  for (const contract of evidence.contracts)
+    if (!/^[a-f0-9]{64}$/.test(contract.sha256))
+      errors.push(`${contract.path}: invalid SHA-256 digest`);
+  const targets = new Set(evidence.lifecycleMatrix.map((row) => `${row.platform}/${row.architecture}`));
+  for (const target of ["darwin/arm64", "darwin/x64", "linux/x64", "win32/x64"])
+    if (!targets.has(target))
+      errors.push(`Craft lifecycle matrix is missing ${target}`);
+  if (evidence.release.signing !== "pending" || evidence.release.notarization !== "pending")
+    errors.push("Craft signing/notarization cannot be promoted without retained release evidence");
+  if (!evidence.release.blockedBy)
+    errors.push("Craft release blocker must be linked");
+  return errors;
+}
+function serializedEvidence() {
+  return `${JSON.stringify(craftEvidence, null, 2)}
+`;
+}
+export async function run() {
+  const errors = validateCraftEvidence(craftEvidence);
+  if (process.argv.includes("--write")) {
+    if (errors.length)
+      throw Error(errors.join(`
+`));
+    writeFileSync(outputPath, serializedEvidence());
+    console.log(`Wrote Craft evidence for ${craftEvidence.source.tag}`);
+  } else if (process.argv.includes("--check")) {
+    if (!existsSync(outputPath))
+      errors.push(".github/protocol/evidence/craft.json is missing");
+    else if (readFileSync(outputPath, "utf8") !== serializedEvidence())
+      errors.push("Craft evidence is stale; run bun run protocol:craft");
+    if (errors.length)
+      throw Error(errors.join(`
+`));
+    console.log(`Craft evidence pins ${craftEvidence.source.tag} at ${craftEvidence.source.revision}`);
+  } else {
+    console.error("usage: bun storage/framework/core/buddy/src/commands/protocol/craft-evidence.ts --write | --check");
+    process.exit(2);
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/craft-evidence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/protocol/craft-evidence.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "bun:test";
+import { craftEvidence, validateCraftEvidence } from "./craft-evidence";
+describe("Craft protocol evidence", () => {
+  it("pins the full native lifecycle and release contract", () => {
+    expect(validateCraftEvidence(craftEvidence)).toEqual([]);
+    expect(craftEvidence.lifecycleMatrix).toHaveLength(4);
+    expect(craftEvidence.lifecycleOperations).toEqual(["install", "launch", "update", "rollback", "uninstall"]);
+  });
+  it("rejects untraceable source and premature signing claims", () => {
+    const invalid = structuredClone(craftEvidence);
+    Object.assign(invalid.source, { tag: "latest", revision: "short" });
+    Object.assign(invalid.release, { signing: "enforced", notarization: "enforced", blockedBy: "" });
+    expect(validateCraftEvidence(invalid)).toEqual(expect.arrayContaining([
+      "Craft tag does not match its version",
+      "Craft revision is not a full commit SHA",
+      "Craft signing/notarization cannot be promoted without retained release evidence",
+      "Craft release blocker must be linked"
+    ]));
+  });
+});

package/dist/commands/protocol/desktop-lifecycle-report.d.ts

@@ -0,0 +1,16 @@
+export declare function validateLifecycleReport(report: LifecycleReport, expected: {
+  revision: string
+  platform: string
+  architecture: string
+  formats: string[]
+}): string[];
+export declare function run(): Promise<void>;
+declare type LifecycleReport = {
+  revision?: string
+  orchestratorRevision?: string | null
+  status?: string
+  installLifecycleExercised?: boolean
+  runner?: { os?: string, arch?: string }
+  artifacts?: Array<{ format?: string, sha256?: string }>
+  steps?: Array<{ name?: string, status?: string }>
+}

package/dist/commands/protocol/desktop-lifecycle-report.js

@@ -0,0 +1,57 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+export function validateLifecycleReport(report, expected) {
+  const errors = [];
+  if (report.revision !== expected.revision)
+    errors.push(`Craft source revision mismatch: ${report.revision || "missing"}`);
+  if (report.status !== "passed")
+    errors.push(`Craft lifecycle status is ${report.status || "missing"}`);
+  if (report.installLifecycleExercised !== !0)
+    errors.push("privileged install lifecycle was not exercised");
+  if (report.runner?.os !== expected.platform || report.runner?.arch !== expected.architecture)
+    errors.push(`runner mismatch: ${report.runner?.os || "missing"}/${report.runner?.arch || "missing"}`);
+  const steps = new Map((report.steps || []).map((step) => [step.name, step.status]));
+  for (const name of ["install v1", "launch v1", "update to v2", "launch v2", "rollback to v1", "launch rollback", "uninstall", "verify uninstall"])
+    if (steps.get(name) !== "passed")
+      errors.push(`lifecycle step did not pass: ${name}`);
+  const artifacts = report.artifacts || [];
+  for (const format of expected.formats) {
+    const matching = artifacts.filter((artifact) => artifact.format === format);
+    if (matching.length !== 2)
+      errors.push(`expected two ${format} artifacts, found ${matching.length}`);
+    if (matching.some((artifact) => !/^[a-f0-9]{64}$/.test(artifact.sha256 || "")))
+      errors.push(`${format} artifact has an invalid digest`);
+  }
+  return errors;
+}
+export async function run() {
+  const value = (name) => {
+    const index = process.argv.indexOf(name), result = index === -1 ? void 0 : process.argv[index + 1];
+    if (!result)
+      throw Error(`${name} requires a value`);
+    return result;
+  }, reportPath = resolve(value("--report")), outputPath = resolve(value("--output")), expected = {
+    revision: value("--revision"),
+    platform: value("--platform"),
+    architecture: value("--architecture"),
+    formats: value("--formats").split(",")
+  }, report = JSON.parse(readFileSync(reportPath, "utf8")), errors = validateLifecycleReport(report, expected);
+  if (errors.length)
+    throw Error(errors.join(`
+`));
+  const attestation = {
+    schemaVersion: 1,
+    status: "passed",
+    stacksRevision: process.env.GITHUB_SHA || "local",
+    craftRevision: expected.revision,
+    sourceReport: reportPath,
+    target: { platform: expected.platform, architecture: expected.architecture, formats: expected.formats },
+    checks: { lifecycle: "passed", artifactDigests: "passed", sourcePin: "passed" }
+  };
+  mkdirSync(dirname(outputPath), { recursive: !0 });
+  writeFileSync(outputPath, `${JSON.stringify(attestation, null, 2)}
+`);
+  console.log(`Validated Craft lifecycle for ${expected.platform}/${expected.architecture}`);
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/desktop-lifecycle-report.test.d.ts

@@ -0,0 +1 @@
+export {};