takt-marp 0.2.1 → 0.3.0

package/README.ja.md

@@ -34,21 +34,21 @@ Output Requirementsの例:
 ### 2. workflowを実行する
 
 ```bash
-npm run slide:plan -- "slides/<deck>"
-npm run slide:approve -- "slides/<deck>" plan --by <name>
-npm run slide:compose -- "slides/<deck>"
-npm run slide:approve -- "slides/<deck>" compose --by <name>
-npm run slide:polish -- "slides/<deck>"
-npm run slide:deliver -- "slides/<deck>"
+takt-marp plan "slides/<deck>"
+takt-marp approve "slides/<deck>" plan --by <name>
+takt-marp compose "slides/<deck>"
+takt-marp approve "slides/<deck>" compose --by <name>
+takt-marp polish "slides/<deck>"
+takt-marp deliver "slides/<deck>"
 ```
 
 targetは `slides/<deck>` を指定します。
 
 ```bash
-npm run slide:plan -- "slides/<deck>"
+takt-marp plan "slides/<deck>"
 ```
 
-人間承認は `plan` と `compose` に対してのみ `slide:approve` で記録します。`review`、`revise`、`qa`、`build-qa` はworkflow内部の責務であり、トップレベルコマンドではありません。
+人間承認は `plan` と `compose` に対してのみ `takt-marp approve` で記録します。`review`、`revise`、`qa`、`build-qa` はworkflow内部の責務であり、トップレベルコマンドではありません。
 
 ### 3. 生成されるファイル
 
@@ -75,24 +75,21 @@ slides/<deck>/
 - spatial balance: 上寄り、左寄り、大きな意図しない余白、視覚重心
 - design-system usage: token化されたCSS、スライドごとのstyle drift防止
 
-`deliver` は要求された成果物を生成します。PDF生成は対象deckの `SLIDES.md` だけをbuildします。
+`deliver` は要求された成果物を生成し、delivery verification と supervision まで行います。
+単純なローカル生成や確認だけなら、workflow state を変更しない utility command を使います。
 
 ```bash
-npm run build:pdf -- <deck>
+takt-marp build:html <deck>
+takt-marp build:pdf <deck>
+takt-marp preview <deck>
 ```
 
 ### 5. 検証
 
-軽量なローカル確認には foundation validation を使います。
-
-```bash
-npm test
-```
-
 workflow routing、state gate、render evidence、delivery verification、approval handling を変更した場合は smoke validation を実行します。
 
 ```bash
-npm run slide:smoke -- --keep
+takt-marp smoke --keep
 ```
 
 smoke validation は fixture から一時的な `_workflow-smoke` deck を作成し、invalid target、approval failure path、`plan` -> `compose` -> `polish` -> `deliver` の一連の実行、render evidence metadata、delivery artifact、rerun/force behavior を検証します。`--keep` を付けると、生成された deck と report を `slides/_workflow-smoke/` に残して確認できます。

package/README.md

@@ -34,21 +34,21 @@ Example output requirement:
 ### 2. Run the workflows
 
 ```bash
-npm run slide:plan -- "slides/<deck>"
-npm run slide:approve -- "slides/<deck>" plan --by <name>
-npm run slide:compose -- "slides/<deck>"
-npm run slide:approve -- "slides/<deck>" compose --by <name>
-npm run slide:polish -- "slides/<deck>"
-npm run slide:deliver -- "slides/<deck>"
+takt-marp plan "slides/<deck>"
+takt-marp approve "slides/<deck>" plan --by <name>
+takt-marp compose "slides/<deck>"
+takt-marp approve "slides/<deck>" compose --by <name>
+takt-marp polish "slides/<deck>"
+takt-marp deliver "slides/<deck>"
 ```
 
 Use `slides/<deck>` as the target:
 
 ```bash
-npm run slide:plan -- "slides/<deck>"
+takt-marp plan "slides/<deck>"
 ```
 
-Human approval is recorded by `slide:approve` for `plan` and `compose` only. `review`, `revise`, `qa`, and `build-qa` are internal workflow responsibilities, not top-level commands.
+Human approval is recorded by `takt-marp approve` for `plan` and `compose` only. `review`, `revise`, `qa`, and `build-qa` are internal workflow responsibilities, not top-level commands.
 
 ### 3. Generated files
 
@@ -75,24 +75,21 @@ slides/<deck>/
 - spatial balance: top/left bias, large unintended blank areas, visual center of gravity
 - design-system usage: tokenized CSS, no per-slide style drift
 
-`deliver` is responsible for requested artifacts. PDF generation builds only the target deck's `SLIDES.md`:
+`deliver` is responsible for requested artifacts, delivery verification, and final supervision.
+For simple local generation or inspection, use utility commands that do not change workflow state:
 
 ```bash
-npm run build:pdf -- <deck>
+takt-marp build:html <deck>
+takt-marp build:pdf <deck>
+takt-marp preview <deck>
 ```
 
 ### 5. Validation
 
-Use the foundation validation for fast local checks:
-
-```bash
-npm test
-```
-
 Use the smoke validation when changing workflow routing, state gates, render evidence, delivery verification, or approval handling:
 
 ```bash
-npm run slide:smoke -- --keep
+takt-marp smoke --keep
 ```
 
 The smoke validation creates a temporary `_workflow-smoke` deck from the fixture, exercises invalid target and approval failure paths, runs the `plan` -> `compose` -> `polish` -> `deliver` sequence, verifies render evidence metadata, checks delivery artifacts, and covers rerun/force behavior. `--keep` leaves the generated deck and reports under `slides/_workflow-smoke/` for inspection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takt-marp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "takt-marp",
   "repository": {
     "type": "git",
@@ -31,10 +31,10 @@
     "slide:smoke": "node scripts/takt-marp-validate-slide-workflow-smoke.mjs",
     "test": "npm run slide:validate-foundation",
     "build": "npm run build:html && npm run build:pdf",
-    "build:html": "marp slides/takt-sdd/SLIDES.md --html --allow-local-files -o dist/takt-sdd/SLIDES.html",
-    "build:pptx": "marp slides/takt-sdd/SLIDES.md --html --allow-local-files --pptx -o dist/takt-sdd/SLIDES.pptx",
-    "build:pdf": "marp slides/takt-sdd/SLIDES.md --html --allow-local-files --pdf -o dist/takt-sdd/SLIDES.pdf",
-    "preview": "marp -s . --html",
+    "build:html": "node scripts/takt-marp-build-slide-artifact.mjs html",
+    "build:pptx": "node scripts/takt-marp-build-slide-artifact.mjs pptx",
+    "build:pdf": "node scripts/takt-marp-build-slide-artifact.mjs pdf",
+    "preview": "node scripts/takt-marp-preview-slide.mjs takt-sdd",
     "installer:sync-templates": "node scripts/takt-marp-sync-project-templates.mjs --write",
     "installer:check-templates": "node scripts/takt-marp-sync-project-templates.mjs",
     "installer:check-package": "node scripts/takt-marp-validate-package-boundary.mjs",

package/scripts/lib/takt-marp-cli.mjs

@@ -13,11 +13,20 @@ import {
 } from "./takt-marp-slide-workflow.mjs";
 
 const WORKFLOW_COMMANDS = ["plan", "compose", "polish", "deliver"];
-const VALID_COMMANDS = ["init", ...WORKFLOW_COMMANDS, "approve", "smoke"];
+const BUILD_COMMANDS = Object.freeze({
+  "build:html": "html",
+  "build:pdf": "pdf",
+  "build:pptx": "pptx",
+});
+const UTILITY_COMMANDS = [...Object.keys(BUILD_COMMANDS), "preview"];
+const VALID_COMMANDS = ["init", ...WORKFLOW_COMMANDS, ...UTILITY_COMMANDS, "approve", "smoke"];
 const RUNNER_SCRIPT = "scripts/takt-marp-run-slide-workflow.mjs";
 const APPROVE_SCRIPT = "scripts/takt-marp-approve-slide-workflow-state.mjs";
 const SMOKE_SCRIPT = "scripts/takt-marp-validate-slide-workflow-smoke.mjs";
+const BUILD_SCRIPT = "scripts/takt-marp-build-slide-artifact.mjs";
+const PREVIEW_SCRIPT = "scripts/takt-marp-preview-slide.mjs";
 const REQUIRED_PROJECT_DIRS = [".takt/workflows", ".takt/facets"];
+const FORWARDED_SIGNALS = new Set(["SIGINT", "SIGTERM"]);
 
 function usage() {
   return [
@@ -29,6 +38,14 @@ function usage() {
     "  compose <slides/deck> [options]   Run the compose workflow for a deck in the current project",
     "  polish <slides/deck> [options]    Run the polish workflow for a deck in the current project",
     "  deliver <slides/deck> [options]   Run the deliver workflow for a deck in the current project",
+    "  build:html [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
+    "                                    Build HTML artifact without changing workflow state",
+    "  build:pdf [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
+    "                                    Build PDF artifact without changing workflow state",
+    "  build:pptx [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
+    "                                    Build PPTX artifact without changing workflow state",
+    "  preview <deck|slides/<deck>|slides/<deck>/SLIDES.md>",
+    "                                    Start Marp server mode without changing workflow state",
     "  approve <slides/deck> <command> --by <name> [--force]",
     "                                    Approve a workflow state (command: plan or compose)",
     "  smoke [--provider <name>]         Run smoke validation in a temporary project (default provider: mock)",
@@ -72,12 +89,39 @@ function assertProjectInitialized() {
 
 function runPackageScript(relativeScriptPath, args, options = {}) {
   return new Promise((resolve, reject) => {
+    let stopping = false;
     const child = spawn(process.execPath, [packageScriptPath(relativeScriptPath), ...args], {
       cwd: options.cwd ?? process.cwd(),
       stdio: "inherit",
     });
-    child.on("error", reject);
-    child.on("close", (code) => {
+    const signalHandlers = [];
+    if (options.successOnSignal) {
+      for (const signal of FORWARDED_SIGNALS) {
+        const handler = () => {
+          stopping = true;
+          if (!child.killed) {
+            child.kill(signal);
+          }
+        };
+        process.once(signal, handler);
+        signalHandlers.push([signal, handler]);
+      }
+    }
+    const cleanup = () => {
+      for (const [signal, handler] of signalHandlers) {
+        process.off(signal, handler);
+      }
+    };
+    child.on("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      cleanup();
+      if (options.successOnSignal && (stopping || FORWARDED_SIGNALS.has(signal))) {
+        resolve(0);
+        return;
+      }
       resolve(code ?? 1);
     });
   });
@@ -88,6 +132,14 @@ async function runWorkflowCommand(command, args) {
   return runPackageScript(RUNNER_SCRIPT, [command, ...args]);
 }
 
+async function runBuildCommand(command, args) {
+  return runPackageScript(BUILD_SCRIPT, [BUILD_COMMANDS[command], ...args]);
+}
+
+async function runPreview(args) {
+  return runPackageScript(PREVIEW_SCRIPT, args, { successOnSignal: true });
+}
+
 async function runInit(args) {
   let parsed;
   try {
@@ -257,6 +309,12 @@ export async function runCli(argv) {
     if (command === "smoke") {
       return await runSmoke(rest);
     }
+    if (Object.hasOwn(BUILD_COMMANDS, command)) {
+      return await runBuildCommand(command, rest);
+    }
+    if (command === "preview") {
+      return await runPreview(rest);
+    }
     return await runWorkflowCommand(command, rest);
   } catch (error) {
     console.error(formatError(error));

package/scripts/lib/takt-marp-slide-artifact-target.mjs

@@ -0,0 +1,70 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { SlideWorkflowError } from "./takt-marp-slide-workflow.mjs";
+
+export async function resolveSlideArtifactTargets(target, options = {}) {
+  if (!target) {
+    return listSlideArtifactTargets(options);
+  }
+  return [resolveSlideArtifactTarget(target, options)];
+}
+
+export async function listSlideArtifactTargets(options = {}) {
+  const root = options.root ?? process.cwd();
+  const slidesRoot = path.join(root, "slides");
+  const entries = await readdir(slidesRoot, { withFileTypes: true });
+  const targets = entries
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => existsSync(path.join(slidesRoot, entry.name, "SLIDES.md")))
+    .map((entry) => resolveSlideArtifactTarget(entry.name, options))
+    .sort((left, right) => left.deckName.localeCompare(right.deckName));
+
+  if (targets.length === 0) {
+    throw new SlideWorkflowError("No slides/*/SLIDES.md files found.", "SLIDES_NOT_FOUND");
+  }
+  return targets;
+}
+
+export function resolveSlideArtifactTarget(target, options = {}) {
+  const root = options.root ?? process.cwd();
+  if (!target || path.isAbsolute(target)) {
+    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
+  }
+
+  const normalized = path.posix.normalize(target.replaceAll(path.sep, "/"));
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
+  }
+
+  const parts = normalized.split("/");
+  const deckName = deckNameFromParts(parts, target);
+  const deckPath = path.join(root, "slides", deckName);
+  const slidesPath = path.join(deckPath, "SLIDES.md");
+  if (!existsSync(slidesPath)) {
+    throw new SlideWorkflowError(`SLIDES.md not found: slides/${deckName}/SLIDES.md`, "SLIDES_NOT_FOUND");
+  }
+
+  return Object.freeze({
+    deckName,
+    deckPath,
+    slidesPath,
+    distPath: path.join(root, "dist", deckName),
+  });
+}
+
+function deckNameFromParts(parts, original) {
+  if (parts.length === 1 && parts[0] && !parts[0].endsWith(".md")) {
+    return parts[0];
+  }
+  if (parts.length === 2 && parts[0] === "slides" && parts[1] && !parts[1].endsWith(".md")) {
+    return parts[1];
+  }
+  if (parts.length === 3 && parts[0] === "slides" && parts[1] && parts[2] === "SLIDES.md") {
+    return parts[1];
+  }
+  throw new SlideWorkflowError(
+    `Invalid deck target '${original}'. Expected deck, slides/<deck>, or slides/<deck>/SLIDES.md.`,
+    "INVALID_TARGET",
+  );
+}

package/scripts/takt-marp-build-slide-artifact.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, readdir } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import {
   formatError,
   parseArgs,
   SlideWorkflowError,
 } from "./lib/takt-marp-slide-workflow.mjs";
+import { resolveSlideArtifactTargets } from "./lib/takt-marp-slide-artifact-target.mjs";
 import { runtimeExecutablePath } from "./lib/takt-marp-runtime-context.mjs";
 
 const ARTIFACT_OPTIONS = Object.freeze({
@@ -23,9 +23,9 @@ function usage() {
     "When deck is omitted, all slides/*/SLIDES.md files are built.",
     "",
     "Examples:",
-    "  npm run build:pdf -- my-talk",
-    "  npm run build:html -- slides/my-talk",
-    "  npm run build:pptx -- slides/my-talk/SLIDES.md",
+    "  takt-marp build:pdf my-talk",
+    "  takt-marp build:html slides/my-talk",
+    "  takt-marp build:pptx slides/my-talk/SLIDES.md",
   ].join("\n");
 }
 
@@ -37,79 +37,19 @@ async function main() {
   }
 
   const [artifact, target] = positional;
+  if (positional.length > 2) {
+    throw new SlideWorkflowError(usage(), "INVALID_ARGS");
+  }
   if (!ARTIFACT_OPTIONS[artifact]) {
     throw new SlideWorkflowError(usage(), "INVALID_ARGS");
   }
 
-  const targets = await resolveBuildTargets(target);
+  const targets = await resolveSlideArtifactTargets(target);
   for (const item of targets) {
     await buildArtifact(artifact, item);
   }
 }
 
-async function resolveBuildTargets(target) {
-  if (!target) {
-    return listDecksWithSlides();
-  }
-  return [resolveBuildTarget(target)];
-}
-
-async function listDecksWithSlides() {
-  const slidesRoot = path.join(process.cwd(), "slides");
-  const entries = await readdir(slidesRoot, { withFileTypes: true });
-  const targets = entries
-    .filter((entry) => entry.isDirectory())
-    .filter((entry) => existsSync(path.join(slidesRoot, entry.name, "SLIDES.md")))
-    .map((entry) => resolveBuildTarget(entry.name))
-    .sort((left, right) => left.deckName.localeCompare(right.deckName));
-
-  if (targets.length === 0) {
-    throw new SlideWorkflowError("No slides/*/SLIDES.md files found.", "SLIDES_NOT_FOUND");
-  }
-  return targets;
-}
-
-function resolveBuildTarget(target) {
-  if (!target || path.isAbsolute(target)) {
-    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
-  }
-
-  const normalized = path.posix.normalize(target.replaceAll(path.sep, "/"));
-  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
-    throw new SlideWorkflowError(`Invalid deck target '${target}'.`, "INVALID_TARGET");
-  }
-
-  const parts = normalized.split("/");
-  const deckName = deckNameFromParts(parts, target);
-  const deckPath = path.join(process.cwd(), "slides", deckName);
-  const slidesPath = path.join(deckPath, "SLIDES.md");
-  if (!existsSync(slidesPath)) {
-    throw new SlideWorkflowError(`SLIDES.md not found: slides/${deckName}/SLIDES.md`, "SLIDES_NOT_FOUND");
-  }
-
-  return Object.freeze({
-    deckName,
-    slidesPath,
-    distPath: path.join(process.cwd(), "dist", deckName),
-  });
-}
-
-function deckNameFromParts(parts, original) {
-  if (parts.length === 1 && parts[0] && !parts[0].endsWith(".md")) {
-    return parts[0];
-  }
-  if (parts.length === 2 && parts[0] === "slides" && parts[1] && !parts[1].endsWith(".md")) {
-    return parts[1];
-  }
-  if (parts.length === 3 && parts[0] === "slides" && parts[1] && parts[2] === "SLIDES.md") {
-    return parts[1];
-  }
-  throw new SlideWorkflowError(
-    `Invalid deck target '${original}'. Expected deck, slides/<deck>, or slides/<deck>/SLIDES.md.`,
-    "INVALID_TARGET",
-  );
-}
-
 async function buildArtifact(artifact, target) {
   await mkdir(target.distPath, { recursive: true });
   const outputPath = path.join(target.distPath, `SLIDES.${artifact}`);

package/scripts/takt-marp-preview-slide.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import {
+  formatError,
+  parseArgs,
+  SlideWorkflowError,
+} from "./lib/takt-marp-slide-workflow.mjs";
+import { resolveSlideArtifactTarget } from "./lib/takt-marp-slide-artifact-target.mjs";
+import { runtimeExecutablePath } from "./lib/takt-marp-runtime-context.mjs";
+
+const PREVIEW_STOP_SIGNALS = new Set(["SIGINT", "SIGTERM"]);
+
+function usage() {
+  return [
+    "Usage: takt-marp preview <deck|slides/<deck>|slides/<deck>/SLIDES.md>",
+    "",
+    "Starts Marp server mode for the target deck directory without running a TAKT workflow.",
+    "",
+    "Examples:",
+    "  takt-marp preview my-talk",
+    "  takt-marp preview slides/my-talk",
+    "  takt-marp preview slides/my-talk/SLIDES.md",
+  ].join("\n");
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    console.log(usage());
+    return;
+  }
+  if (positional.length !== 1) {
+    throw new SlideWorkflowError(usage(), "INVALID_ARGS");
+  }
+
+  const target = resolveSlideArtifactTarget(positional[0]);
+  const marpPath = runtimeExecutablePath("marp");
+  const result = await run(marpPath, [
+    target.deckPath,
+    "--server",
+    "--html",
+    "--allow-local-files",
+  ]);
+  if (!result.ok) {
+    throw new SlideWorkflowError(`Marp preview failed for slides/${target.deckName}/SLIDES.md`, "MARP_PREVIEW_FAILED");
+  }
+}
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    let stopping = false;
+    const child = spawn(command, args, {
+      shell: process.platform === "win32",
+      stdio: "inherit",
+    });
+    const signalHandlers = [];
+    for (const signal of PREVIEW_STOP_SIGNALS) {
+      const handler = () => {
+        stopping = true;
+        if (!child.killed) {
+          child.kill(signal);
+        }
+      };
+      process.once(signal, handler);
+      signalHandlers.push([signal, handler]);
+    }
+    const cleanup = () => {
+      for (const [signal, handler] of signalHandlers) {
+        process.off(signal, handler);
+      }
+    };
+    child.on("error", (error) => {
+      cleanup();
+      reject(
+        new SlideWorkflowError(
+          `Failed to start Marp executable: ${command}. Reinstall takt-marp and verify the @marp-team/marp-cli dependency. ${error.message}`,
+          "MARP_EXECUTABLE_MISSING",
+        ),
+      );
+    });
+    child.on("close", (code, signal) => {
+      cleanup();
+      resolve({ ok: stopping || PREVIEW_STOP_SIGNALS.has(signal) || code === 0 });
+    });
+  });
+}
+
+main().catch((error) => {
+  console.error(formatError(error));
+  process.exit(1);
+});

package/scripts/takt-marp-validate-global-install.mjs

@@ -23,7 +23,19 @@ import { listTemplateEntries } from "./lib/takt-marp-project-templates.mjs";
 import { resolveRuntimeContext } from "./lib/takt-marp-runtime-context.mjs";
 import { SlideWorkflowError, formatError } from "./lib/takt-marp-slide-workflow.mjs";
 
-const CLI_COMMANDS = ["init", "plan", "compose", "polish", "deliver", "smoke"];
+const CLI_COMMANDS = [
+  "init",
+  "plan",
+  "compose",
+  "polish",
+  "deliver",
+  "build:html",
+  "build:pdf",
+  "build:pptx",
+  "preview",
+  "approve",
+  "smoke",
+];
 // Runtime state / provider configuration that init must never generate (8.2).
 const RUNTIME_STATE_NAMES = [
   "config.yaml",
@@ -148,6 +160,12 @@ async function assertFileContent(filePath, expectedContent, label) {
   check(actual === expectedContent, `${label}: file content changed: ${filePath}`);
 }
 
+async function assertNonEmptyFile(filePath, label) {
+  check(existsSync(filePath), `${label}: file is missing: ${filePath}`);
+  const actual = await readFile(filePath);
+  check(actual.length > 0, `${label}: file is empty: ${filePath}`);
+}
+
 // Phase 1 (8.1): real tarball -> temp global prefix; later phases run the CLI
 // from that prefix via PATH.
 async function phasePackInstall(ctx) {
@@ -172,7 +190,7 @@ async function phasePackInstall(ctx) {
   return `tarball ${tarballs[0]} installed into temp prefix`;
 }
 
-// Phase 2 (1.1, 1.2, 1.3): help lists all six commands; slide:* is rejected.
+// Phase 2 (1.1, 1.2, 1.3): help lists all public commands; slide:* is rejected.
 async function phaseSurface(ctx) {
   const help = await runTaktMarp(ctx, ["--help"], { cwd: ctx.workDir });
   check(help.code === 0, `takt-marp --help must exit 0.\n${commandSummary(help)}`);
@@ -189,7 +207,52 @@ async function phaseSurface(ctx) {
     unknown.output.includes("UNKNOWN_COMMAND"),
     `takt-marp slide:plan must be rejected with UNKNOWN_COMMAND.\n${commandSummary(unknown)}`,
   );
-  return "help lists 6 commands; slide:* rejected with UNKNOWN_COMMAND";
+  return "help lists public commands; slide:* rejected with UNKNOWN_COMMAND";
+}
+
+// Phase 2b: utility commands must work from the installed CLI without requiring
+// the target project to own package.json, node_modules, or .takt workflow state.
+async function phaseUtilityCommands(ctx) {
+  const projectDir = path.join(ctx.workDir, "utility-project");
+  const deckDir = path.join(projectDir, "slides", "sample");
+  await mkdir(deckDir, { recursive: true });
+  await writeFile(
+    path.join(deckDir, "SLIDES.md"),
+    [
+      "---",
+      "marp: true",
+      "html: true",
+      "---",
+      "",
+      "# Utility Build",
+      "",
+      "<strong>HTML enabled</strong>",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  check(!existsSync(path.join(projectDir, "package.json")), "precondition: utility project must not have package.json");
+  check(!existsSync(path.join(projectDir, "node_modules")), "precondition: utility project must not have node_modules");
+  check(!existsSync(path.join(projectDir, ".takt")), "precondition: utility project must not have .takt");
+
+  const html = await runTaktMarp(ctx, ["build:html", "slides/sample"], { cwd: projectDir });
+  check(html.code === 0, `takt-marp build:html must exit 0 in a non-npm project.\n${commandSummary(html)}`);
+  await assertNonEmptyFile(path.join(projectDir, "dist", "sample", "SLIDES.html"), "build:html output");
+
+  const pdf = await runTaktMarp(ctx, ["build:pdf", "sample"], { cwd: projectDir });
+  check(pdf.code === 0, `takt-marp build:pdf must exit 0 in a non-npm project.\n${commandSummary(pdf)}`);
+  await assertNonEmptyFile(path.join(projectDir, "dist", "sample", "SLIDES.pdf"), "build:pdf output");
+
+  const previewHelp = await runTaktMarp(ctx, ["preview", "--help"], { cwd: projectDir });
+  check(previewHelp.code === 0, `takt-marp preview --help must exit 0.\n${commandSummary(previewHelp)}`);
+  check(
+    previewHelp.stdout.includes("Usage: takt-marp preview"),
+    `preview help must show preview usage.\n${commandSummary(previewHelp)}`,
+  );
+
+  check(!existsSync(path.join(projectDir, ".takt")), "utility commands must not create .takt workflow state");
+  return "build utilities ran without project package.json/node_modules/.takt; preview help is available";
 }
 
 // Phase 3 (8.2): init generates exactly workflows/** + facets/** under .takt,
@@ -327,6 +390,7 @@ async function phaseMockSmoke(ctx) {
 const PHASES = [
   { name: "pack-install", run: phasePackInstall, deps: [] },
   { name: "surface", run: phaseSurface, deps: [] },
+  { name: "utility-commands", run: phaseUtilityCommands, deps: [] },
   { name: "init-boundary", run: phaseInitBoundary, deps: [] },
   { name: "conflict-force", run: phaseConflictForce, deps: ["init-boundary"] },
   { name: "workflow-command-modes", run: phaseWorkflowCommandModes, deps: ["init-boundary"] },