slidemind 0.3.20 → 0.4.1

package/src/cli/assets.mjs

@@ -0,0 +1,164 @@
+// `slidemind assets import | list` — the deck's image registry.
+//
+// `import` copies a file into the deck, identifies it by its own bytes and
+// records it. That is ALL it does: it decides no fidelity, writes no plan entry
+// and creates no obligation to place the picture anywhere. What an image is FOR
+// is an `assetUses` record the agent writes into the plan, where the user
+// reviews and approves it.
+//
+// It takes filesystem paths only. Acquiring bytes is somebody else's job —
+// `slidemind download-result` for an engine result, the harness's attachment
+// access for something the user pasted into chat, the user's own download for
+// anything else. A command that fetched URLs would be a second, unreviewed way
+// for content to enter a deck.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { deckSlug, fail, resolveDeckArg, resolveDeckRoot } from "./common.mjs";
+import { formatSize } from "../bridge/image-dimensions.mjs";
+import { importImageAsset, readImageAssetManifest } from "../lib/image-assets.mjs";
+
+const USAGE =
+  "usage: slidemind assets import <deck> <file> [--json]\n" +
+  "       slidemind assets list <deck> [--json]";
+
+const emit = (data) => process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+
+const URL_ARG = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+function parseArgs(rest, sub) {
+  const args = { positional: [], json: false };
+  for (const a of rest) {
+    if (a === "--json") args.json = true;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}\n${USAGE}`);
+    else args.positional.push(a);
+  }
+  if (!args.positional.length) fail(`slidemind assets ${sub} needs a deck.\n${USAGE}`);
+  return args;
+}
+
+// The deck a user named, resolved to its workspace. A deck that is not there
+// yet is the one mistake worth naming precisely — `assets import` is often the
+// first thing an agent runs in a session.
+function deckFor(name) {
+  const root = resolveDeckRoot(name);
+  if (!fs.existsSync(root)) {
+    fail(`no deck at ${root} — create it first with \`slidemind new ${path.basename(root)}\``);
+  }
+  return resolveDeckArg(name);
+}
+
+function failTyped(err, asJson) {
+  if (!err?.code) throw err;
+  if (asJson) {
+    emit({ ok: false, error: err.code, message: err.message, action: err.issue?.action ?? null });
+    process.exit(1);
+  }
+  fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+}
+
+// ---------------------------------------------------------------------------
+// import
+// ---------------------------------------------------------------------------
+
+async function cmdImport(rest) {
+  const args = parseArgs(rest, "import");
+  const [deckArg, source, ...extra] = args.positional;
+  if (!source) fail(`slidemind assets import needs a file to import.\n${USAGE}`);
+  if (extra.length) fail(`unexpected argument: ${extra[0]}\n${USAGE}`);
+  if (URL_ARG.test(source)) {
+    fail(
+      `assets import takes a file path, not a URL. Download the image first ` +
+        `(\`slidemind download-result\` for an engine result), then import the file.`,
+    );
+  }
+  const deckDir = deckFor(deckArg);
+
+  let result;
+  try {
+    result = await importImageAsset(deckDir, source, { provenance: { kind: "local" } });
+  } catch (err) {
+    failTyped(err, args.json);
+  }
+  const { asset, reused, plan } = result;
+
+  if (args.json) {
+    // Exactly the contract's import result — nothing else is promised here.
+    emit({
+      assetId: asset.assetId,
+      sha256: asset.sha256,
+      mimeType: asset.mimeType,
+      width: asset.width,
+      height: asset.height,
+      byteLength: asset.byteLength,
+      workspacePath: asset.workspacePath,
+      reused,
+    });
+  } else {
+    process.stdout.write(
+      `${reused ? "Already imported" : "Imported"} ${asset.displayName} as ${asset.assetId}\n` +
+        `  ${asset.workspacePath}  ${asset.mimeType}  ${formatSize(asset) ?? "size unknown"}  ${asset.byteLength} bytes\n` +
+        (reused ? "  Same bytes as an existing asset — its identity is kept.\n" : ""),
+    );
+  }
+  // Rendering facts, never on stdout: a --json payload stays exactly the
+  // contract's shape.
+  for (const note of plan.notes) process.stderr.write(`note: ${note}\n`);
+  if (!args.json) {
+    process.stdout.write(
+      `Importing records the bytes only. Give it a use in the plan (assetUses: original | ` +
+        `reconstruct | reference) — that is what makes it appear on a slide.\n`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+
+async function cmdList(rest) {
+  const args = parseArgs(rest, "list");
+  const [deckArg, ...extra] = args.positional;
+  if (extra.length) fail(`unexpected argument: ${extra[0]}\n${USAGE}`);
+  const deckDir = deckFor(deckArg);
+
+  let manifest;
+  try {
+    manifest = readImageAssetManifest(deckDir);
+  } catch (err) {
+    failTyped(err, args.json);
+  }
+
+  if (args.json) {
+    emit({ assets: manifest.assets });
+    return;
+  }
+  if (!manifest.assets.length) {
+    process.stdout.write(
+      `No image assets in ${deckSlug(deckDir)}. Import one with ` +
+        `\`slidemind assets import ${deckSlug(deckDir)} <file>\`.\n`,
+    );
+    return;
+  }
+  const lines = manifest.assets.map(
+    (a) =>
+      `  ${a.assetId}  ${a.mimeType}  ${formatSize(a) ?? "?"}  ${a.byteLength} bytes  ` +
+      `${a.provenance.kind}${a.provenance.sourceId ? ` ${a.provenance.sourceId}` : ""}  ${a.displayName}\n` +
+      `    ${a.workspacePath}  sha256 ${a.sha256}`,
+  );
+  process.stdout.write(
+    `${manifest.assets.length} image asset(s) in ${deckSlug(deckDir)}:\n${lines.join("\n")}\n`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+const SUBCOMMANDS = { import: cmdImport, list: cmdList };
+
+export async function cmdAssets(rest) {
+  const [sub, ...args] = rest;
+  const run = SUBCOMMANDS[sub];
+  if (!run) fail(sub ? `unknown assets subcommand: ${sub}\n${USAGE}` : USAGE);
+  await run(args);
+}

package/src/cli/common.mjs

@@ -3,9 +3,19 @@
 
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import {
+  deckRoot,
+  deckSlug,
+  resolveWorkspace,
+  statePath,
+} from "../lib/deck-paths.mjs";
+import { journalIncomplete } from "../lib/revision.mjs";
+import { addDeck, addRoot, listRoots, migrateBestEffort, registryPath } from "../workspace/registry.mjs";
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
@@ -29,9 +39,10 @@ export function fail(msg, code = 1) {
 // The two human checkmarks the CLI enforces itself, so no harness timeout,
 // context loss, or agent rationalisation can walk past a gate: nothing after
 // the plan gate (concepts, build, view-draft, review) runs on an unapproved or
-// since-edited plan, and nothing ships (push, build-pptx) from a preview the
-// user has not approved exactly as it stands. Both fast-fail before any
-// bridge call with the command that clears them.
+// since-edited plan, and nothing ships (push, build-pptx) from a deck whose
+// preview the user never approved. That second one is one-time per deck: the
+// approval builds the deck, and later changes go straight into the .pptx.
+// Both fast-fail before any bridge call with the command that clears them.
 export async function requirePlanApproved(deckDir) {
   const plan = await import(pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href);
   const why = plan.requirePlanApproved(deckDir);
@@ -44,14 +55,37 @@ export async function requireReviewApproved(deckDir) {
   if (why) fail(why);
 }
 
+// The third precondition on shipping, and the only one that is not a human
+// checkmark: a slide under an open edit scope may not be replaced while what it
+// promised to preserve is unmet or simply unproven. Drafts report those by
+// element id (`[preserve:warn]`); this is where they refuse.
+export async function requireSlidesPreserved(deckDir) {
+  const check = await import(pathToFileURL(path.join(BUILDERS_DIR, "draft-check.mjs")).href);
+  const { blocker, note } = await check.preservationBlocker(deckDir);
+  if (blocker) fail(blocker);
+  // Shipped, but not certified: an obligation only the final package can prove
+  // is a stated limitation, never a silent pass.
+  if (note) process.stderr.write(`  note: ${note}\n`);
+}
+
+// The fourth: nothing reaches the user that `view-draft` has not checked. Every
+// slide this delivery renders (`files`; default every authored slide) needs a
+// check of its current bytes with no defect standing — the review is one-time
+// per deck, so this is what holds an edit made after it.
+export async function requireSlidesDraftChecked(deckDir, { files = null } = {}) {
+  const check = await import(pathToFileURL(path.join(BUILDERS_DIR, "draft-check.mjs")).href);
+  const why = check.draftCheckBlocker(deckDir, { files });
+  if (why) fail(`${deckSlug(deckDir)} cannot be delivered yet — ${why}`);
+}
+
 // A render that stalls on "Multiple PowerPoint windows are open" is, for an
 // UNBOUND deck, really a binding problem: bound, the deck renders pane-free
 // and never asks. Name that fix first — the window pick is the workaround.
 export function withUnboundHint(deckDir, err) {
   const msg = err?.message ?? String(err);
   if (!/Multiple PowerPoint windows are open/.test(msg)) return msg;
-  if (fs.existsSync(path.join(deckDir, ".bundle-ref.json"))) return msg;
-  const slug = path.basename(deckDir);
+  if (fs.existsSync(statePath(deckDir, "bundle-ref.json"))) return msg;
+  const slug = deckSlug(deckDir);
   return (
     `deck ${slug} is not bound to a corporate design, so the render has to go through an open window. ` +
     `Bind it once and no window is needed: \`slidemind ready ${slug}\` (or \`--brand <presFP>\` to name the design). ` +
@@ -75,9 +109,9 @@ export function resolveDecksDir() {
   return path.resolve(process.cwd(), "decks");
 }
 
-export function resolveDeckArg(arg) {
-  // A user can pass either "decks/foo" (relative to CWD), "/abs/path/foo",
-  // or just "foo" — in which case we look it up under the resolved decks dir.
+// The deck ROOT a user named — "decks/foo" (relative to CWD), "/abs/path/foo",
+// or just "foo", which is looked up under the resolved decks dir.
+export function resolveDeckRoot(arg) {
   if (!arg) return null;
   if (path.isAbsolute(arg)) return arg;
   if (fs.existsSync(path.resolve(process.cwd(), arg))) {
@@ -87,16 +121,140 @@ export function resolveDeckArg(arg) {
   return path.join(decksDir, arg);
 }
 
+// What every command works on: the deck's WORKSPACE. `<deck>/.slidemind` when
+// it exists, the deck directory itself otherwise — see src/lib/deck-paths.mjs.
+// The resolved path is announced once (stderr, so --json payloads stay clean)
+// whenever it is not the directory the user typed: `.slidemind/` is hidden in
+// Finder and in most editors, so a silent redirect is a path nobody can find.
+const announced = new Set();
+export function resolveDeckArg(arg, { allowUnfinished = false } = {}) {
+  const root = resolveDeckRoot(arg);
+  if (!root) return root;
+  // A flat pre-workspace deck moves into `.slidemind/` before anything resolves
+  // against it, so this command and the library see one layout.
+  if (workspaceEnabled()) migrateBestEffort(root);
+  const workspace = resolveWorkspace(root);
+  // An interrupted adopt or rebase leaves half a generation on disk, and a build
+  // that silently ships it. The journal is the only record that the operation was
+  // in flight, so every command refuses until it is finished — except the ones
+  // that finish it.
+  if (!allowUnfinished) {
+    const unfinished = journalIncomplete(workspace);
+    if (unfinished) {
+      fail(
+        `deck ${deckSlug(workspace)} has an unfinished ${unfinished.op} (started ${unfinished.startedAt}) — ` +
+          `nothing on disk is a complete generation yet. Finish it first: ` +
+          (unfinished.op === "rebase"
+            ? `\`slidemind rebase ${arg} --incoming ${unfinished.detail?.revisionId ?? "<revisionId>"}\``
+            : `re-run the \`slidemind ${unfinished.op}\` that was interrupted`),
+      );
+    }
+  }
+  if (workspace !== root && !announced.has(workspace)) {
+    announced.add(workspace);
+    process.stderr.write(`slidemind: workspace ${workspace}\n`);
+  }
+  registerDeckHook(workspace);
+  return workspace;
+}
+
+// The one place every deck command feeds the persistent workspace library
+// (src/workspace/registry.mjs): a deck resolved here, adopted, or created is
+// listed the next time the user opens `slidemind workspace`. Off until the
+// user has opted in — SLIDEMIND_WORKSPACE=1 or a registry already on disk —
+// so nothing changes for people who never launched it. SLIDEMIND_WORKSPACE=0
+// opts out even with a registry (headless replays, a user who wants the
+// standalone review pages back). Best effort: a deck
+// that is not yet a deck (open creates `.slidemind/` first) is skipped
+// silently, a registry that cannot be written warns on stderr, and neither
+// ever fails the command. Scratch decks — a deck nested inside another
+// workspace, or one under the OS temp dir — are registered hidden so the
+// library never shows a designer's throwaway or the pack's reference adopt.
+const registered = new Set();
+export function workspaceEnabled() {
+  if (process.env.SLIDEMIND_WORKSPACE === "0") return false;
+  return process.env.SLIDEMIND_WORKSPACE === "1" || fs.existsSync(registryPath());
+}
+export function registerDeckHook(deckDir, { hidden = null } = {}) {
+  if (!deckDir || registered.has(deckDir)) return null;
+  if (!workspaceEnabled()) return null;
+  registered.add(deckDir);
+  try {
+    const entry = addDeck(deckDir, { hidden: hidden ?? isScratchDeck(deckDir) });
+    if (!entry.hidden) rememberDecksRoot(entry.path);
+    return entry;
+  } catch (err) {
+    if (err?.code === "not_a_deck" || err?.code === "missing_path") return null;
+    // An agent's sandbox may not write the library: expected, and harmless — the
+    // workspace (outside the sandbox) registers the deck when a question is asked.
+    // A line about it only reads to the agent as a failure.
+    if (["EPERM", "EACCES", "EROFS"].includes(err?.code) && (process.env.CODEX_SANDBOX || process.env.CODEX_SANDBOX_NETWORK_DISABLED)) return null;
+    process.stderr.write(`slidemind: workspace registry skipped ${deckDir}: ${err.message}\n`);
+    return null;
+  }
+}
+
+// A deck under the configured decks dir that no remembered root covers makes
+// that decks dir a root, so the next CLI version's auto-discovery finds its
+// siblings too. Only the resolver's decks dir qualifies — never $HOME, never an
+// arbitrary parent.
+function rememberDecksRoot(deckReal) {
+  try {
+    const decksDir = fs.realpathSync(resolveDecksDir());
+    if (path.dirname(deckReal) !== decksDir || decksDir === fs.realpathSync(os.homedir())) return;
+    if (listRoots().some((r) => deckReal === r || deckReal.startsWith(r + path.sep))) return;
+    addRoot(decksDir);
+  } catch {
+    // best effort, like the registration itself
+  }
+}
+
+function isScratchDeck(deckDir) {
+  const root = path.resolve(deckRoot(deckDir));
+  if (path.dirname(root).split(path.sep).includes(".slidemind")) return true;
+  const tmp = os.tmpdir();
+  let real = tmp;
+  try {
+    real = fs.realpathSync(tmp);
+  } catch {}
+  return root.startsWith(tmp + path.sep) || root.startsWith(real + path.sep);
+}
+
+export { deckRoot, deckSlug, resolveWorkspace, statePath };
+
+// A harness that stops a command signals the pid it started — this one. The
+// script must stop with it: an orphaned gate keeps waiting (the page says an
+// agent is listening while nobody is) and a standalone gate keeps its port.
+const FORWARDED_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+
 export function runNode(script, args) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [script, ...args], {
       stdio: "inherit",
       env: process.env,
     });
-    child.on("error", reject);
-    child.on("exit", (code) => {
+    const forward = (sig) => {
+      try {
+        child.kill(sig);
+      } catch {
+        // already gone
+      }
+    };
+    for (const sig of FORWARDED_SIGNALS) process.on(sig, forward);
+    const release = () => {
+      for (const sig of FORWARDED_SIGNALS) process.off(sig, forward);
+    };
+    child.on("error", (err) => {
+      release();
+      reject(err);
+    });
+    child.on("exit", (code, signal) => {
+      release();
+      // stopped by a signal: end this process the same way, as if it had no child
+      if (signal) return process.kill(process.pid, signal);
       if (code === 0) resolve();
-      else reject(new Error(`${path.basename(script)} exited with code ${code}`));
+      // the script's own code is the command's (a gate's BLOCKED is 2, not 1)
+      else reject(Object.assign(new Error(`${path.basename(script)} exited with code ${code}`), { exitCode: code }));
     });
   });
 }
@@ -159,7 +317,10 @@ export async function freshenDeckBundle(deckDir) {
   );
   const sync = await bundle.refreshDeckBundle(deckDir);
   if (sync?.changed) {
-    process.stdout.write(
+    // stderr: every command that refreshes the bundle (`view-draft`,
+    // `build-pptx`, `concepts`, `push`) also has a `--json` mode, and a bundle
+    // that happened to move mid-session must not land in front of the payload.
+    process.stderr.write(
       `  design bundle updated (${sync.result.downloaded} file(s) changed) — building against the current corporate design\n`,
     );
   }

package/src/cli/concept-spec-support.mjs

@@ -0,0 +1,76 @@
+// What `concepts` and `transcribe` say when the paired add-in cannot read
+// mockups into concept specs (it does not advertise `conceptSpecs`).
+//
+// The mockups are still generated, so nothing looks broken — and that was the
+// failure: the only signal used to be a `specsSkipped` string inside the
+// `--json` payload. In the 2026-10-06 proposal sim the prod add-in predated
+// the spec reader, `transcribe` had nothing to work from, and the designer
+// agent hand-built two slides that looked nothing like their mockups without
+// anything on screen saying why. So both commands now name the add-in that
+// said no, say what it means for `transcribe`, and use the same words.
+
+export const SPECS_UNSUPPORTED_CODE = "concept_specs_unsupported";
+/** The `specsSkipped` reason `concepts` has always printed for this case. */
+export const SPECS_UNSUPPORTED = "this add-in does not extract concept specs";
+
+const slideList = (slides) =>
+  slides.length === 1 ? `slide ${slides[0]}` : `slides ${slides.join(", ")}`;
+
+/** "the 'prod' add-in (https://…)" — named even with one backend paired. */
+function addin({ env, backendURL }) {
+  if (!backendURL) return "the paired add-in";
+  let host = null;
+  try {
+    host = new URL(backendURL).hostname;
+  } catch {}
+  // An unrecognised host derives no env name, only the host itself.
+  return env && env !== host ? `the '${env}' add-in (${backendURL})` : `the add-in at ${backendURL}`;
+}
+
+function headline(support) {
+  return support.status === "unknown"
+    ? `could not confirm that ${addin(support)} extracts concept specs — it did not answer the capability probe and returned none`
+    : `${addin(support)} does not extract concept specs (it does not advertise \`conceptSpecs\`: its release predates the spec reader)`;
+}
+
+const REBUILD =
+  "Rebuild each of them from its mockup PNG by hand (workflow/create.md): count the mockup's cards, connectors, " +
+  "icons, bands and numbers first and build every one; or pair an add-in that reads specs (`slidemind whoami` " +
+  "lists the paired environments).";
+
+/** `concepts --json` → `specsUnsupported`: null unless the add-in refused. */
+export function specsUnsupportedPayload(support, deck) {
+  if (!support) return null;
+  const slides = support.slides ?? [];
+  return {
+    code: SPECS_UNSUPPORTED_CODE,
+    env: support.env ?? null,
+    backendURL: support.backendURL ?? null,
+    confirmed: support.status !== "unknown",
+    slides,
+    transcribe: "refuses",
+    message: `${headline(support)}. ${slides.length ? `${slideList(slides)} ${slides.length === 1 ? "has" : "have"} a mockup and no spec, so \`slidemind transcribe ${deck}\` cannot build ${slides.length === 1 ? "it" : "them"}.` : ""}`.trim(),
+  };
+}
+
+/** The stderr block `concepts` prints — always, `--json` included. */
+export function specsUnsupportedWarning(support, deck) {
+  const slides = support.slides ?? [];
+  const tag = "slidemind: [specs:warning]";
+  return [
+    `${tag} NO CONCEPT SPECS — ${headline(support)}.`,
+    `${tag} ${slides.length ? `${slideList(slides)} ${slides.length === 1 ? "has" : "have"} a mockup but no spec` : "these mockups have no spec"}, so \`slidemind transcribe ${deck}\` has nothing to build ${slides.length === 1 ? "it" : "them"} from and refuses; re-running \`concepts\` against this add-in will not change that.`,
+    `${tag} ${REBUILD}`,
+  ];
+}
+
+/** `transcribe`'s refusal: the slides it cannot build, and why no re-run helps. */
+export function transcribeSpecsRefusal(support, { deck, slides }) {
+  const which = slides.length
+    ? `${slideList(slides)} ${slides.length === 1 ? "has" : "have"} no concept spec`
+    : "this deck has no concept spec";
+  return (
+    `[specs:error] ${headline(support)}, and ${which} — there is nothing to transcribe, and re-running ` +
+    `\`slidemind concepts ${deck}\` against this add-in will not change that. ${REBUILD} Nothing was written.`
+  );
+}