dev-loops 0.4.0 → 0.6.0

package/lib/dev-loops-core.mjs

@@ -9,6 +9,19 @@ const LOCAL_READINESS_IDS = ['subagent-command', 'git-repo'];
 const REMOTE_READINESS_IDS = ['gh-installed', 'gh-auth', 'subagent-command', 'git-repo'];
 const INSPECT_ACTIONS = new Set(['open', 'resume', 'status', 'stop', 'restart']);
 
+// Direct dev-loop entrypoints (#972): thin named wrappers over the public dev-loop contract.
+// Each maps `<verb> <issue|pr>` to the canonical public-intent shorthand the `dev-loop` skill
+// already accepts — no new routing/strategy logic lives here. `start`/`auto` target an issue,
+// `continue` (#988) targets an issue OR a PR (the resolver picks the canonical artifact) and
+// also accepts a bare form (no number) that continues the current in-progress board item;
+// `info` is the read-only state shortcut for an issue or PR.
+const ENTRYPOINT_VERBS = {
+  start: { target: 'issue', phrase: (n) => `start dev loop on issue ${n}` },
+  auto: { target: 'issue', phrase: (n) => `auto dev loop on issue ${n}` },
+  continue: { target: 'either', allowBare: true, phrase: (n) => (n ? `continue dev loop on ${n}` : 'continue the current dev loop') },
+  info: { target: 'either', phrase: (n) => `inspect dev loop state on ${n}` },
+};
+
 const UNICODE_SPACE_RE = /[\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]/g;
 
 function normalizeInput(input) {
@@ -88,6 +101,100 @@ function parseInspectCommand(tokens, { surface }) {
   };
 }
 
+// Normalize a single entrypoint target token to a bare issue/PR number.
+// Accepts `123`, `#123`, or a GitHub issue/PR URL (.../issues/123 or .../pull/123).
+// Returns the numeric string, or null when it is not a recognized target.
+function normalizeTargetNumber(raw) {
+  const token = String(raw).trim();
+  if (/^#?\d+$/.test(token)) {
+    return token.replace(/^#/, '');
+  }
+  const urlMatch = token.match(/^https?:\/\/[^\s]*\/(?:issues|pull)\/(\d+)(?:[/?#].*)?$/);
+  if (urlMatch) {
+    return urlMatch[1];
+  }
+  return null;
+}
+
+// `start-spike` is a SIBLING of the numeric verbs (start/auto/continue/info): it
+// takes FREE TEXT (a question) or `--file <path>`, NOT a numeric target, so it is
+// parsed on its own path to keep the numeric-validation invariant of the other
+// verbs intact (#988 P2). It is a thin wrapper over the shipped `--spike` intake:
+// the inline-question form scaffolds a startable findings artifact, then both
+// forms hand the resolved spike path to `loop startup --spike <path>`. No new
+// spike behavior lives here — see skills/docs/spike-mode-contract.md.
+function parseStartSpikeCommand(rest, tokens) {
+  const positional = rest.filter((t) => t !== undefined);
+  // `--file <path>`: start from a pre-authored spike artifact (no scaffolding).
+  if (positional[0] === '--file') {
+    const file = positional[1];
+    // Reject any leading `-`: the path is forwarded to `resolve-dev-loop-startup
+    // --spike <path>`, so a value like `-x` could be read as an option (option
+    // injection). Fail closed. The free-text question path below is unaffected.
+    if (typeof file !== 'string' || file.length === 0 || file.startsWith('-') || positional.length !== 2) {
+      return invalidCommand('`start-spike --file` requires exactly one `<path>`.', 'start-spike', tokens);
+    }
+    return {
+      kind: 'start_spike',
+      mode: 'file',
+      file,
+      question: null,
+      intent: `start a dev-loop spike from ${file}`,
+      tokens,
+    };
+  }
+  // Inline free-text question. Joined verbatim so multi-word questions survive.
+  const question = positional.join(' ').trim();
+  if (question.length === 0) {
+    return invalidCommand('`start-spike` requires a question (or `--file <path>`).', 'start-spike', tokens);
+  }
+  return {
+    kind: 'start_spike',
+    mode: 'question',
+    file: null,
+    question,
+    intent: `start a dev-loop spike on the question: ${question}`,
+    tokens,
+  };
+}
+
+function parseEntrypointCommand(action, args, tokens) {
+  const spec = ENTRYPOINT_VERBS[action];
+  const positional = args.filter((a) => a !== undefined);
+  const targetHint = spec.target === 'pr' ? '<pr>' : spec.target === 'either' ? '<issue|pr>' : '<issue>';
+  const targetNoun = spec.target === 'pr' ? 'PR' : spec.target === 'either' ? 'issue/PR' : 'issue';
+
+  // Bare form (no target): only verbs that opt in (e.g. `continue` resumes the
+  // current in-progress board item). The command/skill does the board resolve.
+  if (positional.length === 0 && spec.allowBare) {
+    return {
+      kind: 'entrypoint',
+      action,
+      target: spec.target,
+      number: null,
+      intent: spec.phrase(null),
+      tokens,
+    };
+  }
+
+  if (positional.length !== 1) {
+    const arity = spec.allowBare ? `at most one ${targetHint}` : `exactly one ${targetHint}`;
+    return invalidCommand(`\`${action}\` requires ${arity} argument.`, action, tokens);
+  }
+  const number = normalizeTargetNumber(positional[0]);
+  if (number === null) {
+    return invalidCommand(`\`${action}\` expects a numeric ${targetNoun}, got: ${positional[0]}.`, action, tokens);
+  }
+  return {
+    kind: 'entrypoint',
+    action,
+    target: spec.target,
+    number,
+    intent: spec.phrase(number),
+    tokens,
+  };
+}
+
 export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
   const tokens = normalizeInput(input);
   const [rawAction, rawScope, ...rest] = tokens;
@@ -98,6 +205,15 @@ export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
     return parseInspectCommand(tokens, { surface });
   }
 
+  // `start-spike` is free-text/path, not a numeric verb — parsed on its own path.
+  if (action === 'start-spike') {
+    return parseStartSpikeCommand([rawScope, ...rest], tokens);
+  }
+
+  if (action && Object.prototype.hasOwnProperty.call(ENTRYPOINT_VERBS, action)) {
+    return parseEntrypointCommand(action, [rawScope, ...rest], tokens);
+  }
+
   switch (action) {
     case undefined:
     case '':
@@ -255,6 +371,31 @@ export async function executeDevLoopsCommand({ input, surface = 'extension', run
     }
   }
 
+  if (parsed.kind === 'start_spike') {
+    // Thin wrapper: surface the spike intent so the operator dispatches it through
+    // the dev-loop skill, which scaffolds (inline question) or uses the given file,
+    // then runs `loop startup --spike <path>`. No spike behavior is decided here.
+    return {
+      kind: 'start_spike',
+      mode: parsed.mode,
+      file: parsed.file,
+      question: parsed.question,
+      intent: parsed.intent,
+    };
+  }
+
+  if (parsed.kind === 'entrypoint') {
+    // Thin wrapper: surface the canonical public intent so the user dispatches it through the
+    // `dev-loop` skill (the single public router). No routing/strategy decision is made here.
+    return {
+      kind: 'entrypoint',
+      action: parsed.action,
+      target: parsed.target,
+      number: parsed.number,
+      intent: parsed.intent,
+    };
+  }
+
   if (parsed.kind !== 'action') {
     return parsed;
   }

package/package.json

@@ -25,10 +25,14 @@
     "test": "npm run test:assets && npm run test:extension && npm run test:scripts && npm run test:core && npm run test:docs",
     "test:assets": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/dev-loop-init-phase-smoke.test.mjs test/contracts/*.test.mjs test/workflow-handoff-contract.test.mjs",
     "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/extension-claude-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
-    "test:scripts": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs",
+    "test:scripts": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
     "test:core": "node --test --test-reporter ./test/failure-summary-reporter.mjs packages/core/test/*.test.mjs",
     "test:dev-loop": "node --test --test-reporter ./test/failure-summary-reporter.mjs skills/dev-loop/scripts/dev-mode-context.test.mjs skills/dev-loop/scripts/render-template.test.mjs skills/dev-loop/scripts/post-gate-verdict-fallback.test.mjs",
     "test:playwright:viewer": "playwright test -c playwright.inspect-run-viewer.config.mjs",
+    "test:playwright:deep-dive": "playwright test -c playwright.dev-loops-deep-dive.config.mjs",
+    "test:playwright:intro-deck": "playwright test -c playwright.intro-deck.config.mjs",
+    "test:playwright:intro-article": "playwright test -c playwright.intro-article.config.mjs",
+    "test:playwright:deep-dive-article": "playwright test -c playwright.deep-dive-article.config.mjs",
     "smoke:headless": "node scripts/claude/headless-info-smoke.mjs",
     "test:docs": "node scripts/docs/validate-links.mjs && node scripts/docs/validate-no-duplicate-rules.mjs",
     "repo-wiki": "node scripts/repo-wiki.mjs",
@@ -68,7 +72,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.4.0"
+    "@dev-loops/core": "^0.6.0"
   },
   "repository": {
     "type": "git",
@@ -78,7 +82,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "files": [
     "cli/",
     "lib/",
@@ -89,6 +93,7 @@
     ".claude-plugin/",
     ".claude/.claude-plugin/",
     ".claude/agents/",
+    ".claude/commands/",
     ".claude/skills/",
     ".claude/hooks/",
     "README.md",

package/scripts/claude/generate-claude-assets.mjs

@@ -14,7 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { transformAgent, transformSkill, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
+import { transformAgent, transformSkill, transformCommand, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
 
 /**
  * Collect the generated assets as { target, content } pairs (target is repo-relative).
@@ -45,6 +45,19 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
     }
   }
 
+  // Direct slash commands (#972): thin generated wrappers over the public dev-loop contract,
+  // one `.claude/commands/<name>.md` per `commands/<name>.command.md` source. No routing logic.
+  const commandsDir = path.join(repoRoot, "commands");
+  if (fs.existsSync(commandsDir)) {
+    for (const entry of fs.readdirSync(commandsDir).sort()) {
+      if (!entry.endsWith(".command.md")) continue;
+      const source = `commands/${entry}`;
+      const raw = fs.readFileSync(path.join(repoRoot, source), "utf8");
+      const base = entry.slice(0, -".command.md".length);
+      assets.push({ target: `.claude/commands/${base}.md`, content: transformCommand({ source, raw, version }) });
+    }
+  }
+
   const skillsDir = path.join(repoRoot, "skills");
   if (fs.existsSync(skillsDir)) {
     for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -171,6 +184,7 @@ function listFilesRecursive(repoRoot, rel) {
 function listExistingAssetFiles(repoRoot) {
   const files = [
     ...listFilesRecursive(repoRoot, ".claude/agents"),
+    ...listFilesRecursive(repoRoot, ".claude/commands"),
     ...listFilesRecursive(repoRoot, ".claude/skills"),
   ];
   // `.claude/hooks/` mixes hand-authored scripts (hooks.json, _hook-io.mjs, the three hook

package/scripts/github/capture-review-threads.mjs

@@ -11,6 +11,7 @@ import {
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 export const REVIEW_THREADS_QUERY = [
   "query($owner: String!, $name: String!, $pr: Int!) {",
   "  repository(owner: $owner, name: $name) {",
@@ -45,9 +46,11 @@ Modes:
 Options:
   --output <path>   Write JSON output to file in addition to stdout
   --help, -h        Show this help
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 export function parseCaptureCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -58,6 +61,7 @@ export function parseCaptureCliArgs(argv) {
       output: { type: "string" },
       repo: { type: "string" },
       pr: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -69,6 +73,8 @@ export function parseCaptureCliArgs(argv) {
     repo: undefined,
     pr: undefined,
     help: false,
+    jq: undefined,
+    silent: false,
   };
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -97,6 +103,14 @@ export function parseCaptureCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token));
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   const hasLiveArgs = options.repo !== undefined || options.pr !== undefined;
@@ -188,10 +202,14 @@ export async function runCli(
   if (options.outputPath) {
     await writeOutputFile(options.outputPath, payload);
   }
-  stdout.write(`${JSON.stringify(payload)}\n`);
+  return emitResult(payload, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

package/scripts/github/comment-issue.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: comment-issue.mjs --repo <owner/name> --issue <number> (--body <text> | --body-file <path>)
+Post a comment on a GitHub issue. Thin wrapper over \`gh issue comment\` — use this
+instead of an agent-level raw \`gh issue comment\` so the loop's internal-tooling
+record stays clean (#993; the read-side siblings are list-issues.mjs / fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --issue <number>              Issue number to comment on
+  --body <text>                 Comment body as a single argument
+  --body-file <path>            Read the comment body from a file (preserves
+                                newlines; alternative to --body; - reads stdin)
+Output (stdout, JSON):
+  { "ok": true, "repo": "owner/repo", "issue": 17, "commentUrl": "https://github.com/owner/repo/issues/17#issuecomment-123" }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseCommentIssueCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      body: { type: "string" },
+      "body-file": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    issue: undefined,
+    body: undefined,
+    bodyFile: undefined,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "body") {
+      options.body = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "body-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
+      if (rawPath.length === 0) {
+        throw parseError("--body-file must be a non-empty path");
+      }
+      options.bodyFile = rawPath;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.issue === undefined) {
+    throw parseError("Commenting on an issue requires both --repo <owner/name> and --issue <number>");
+  }
+  if (options.body === undefined && options.bodyFile === undefined) {
+    throw parseError("Commenting on an issue requires --body <text> or --body-file <path>");
+  }
+  if (options.body !== undefined && options.bodyFile !== undefined) {
+    throw parseError("--body and --body-file are mutually exclusive; pass only one");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+async function resolveBody(options) {
+  if (options.bodyFile === undefined) {
+    if (options.body.trim().length === 0) {
+      throw new Error("--body must not be empty");
+    }
+    return options.body;
+  }
+  const source = options.bodyFile === "-" ? 0 : options.bodyFile;
+  const body = await readFile(source, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Post the comment via `gh issue comment`, then read its URL back from
+// `gh issue comment` output. `gh issue comment` prints the new comment URL on
+// success — capture it so callers don't need a follow-up read.
+export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const body = await resolveBody(options);
+  const result = await run(
+    ghCommand,
+    ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue comment failed: ${detail}`);
+  }
+  // `gh issue comment` prints the created comment's URL (the last non-empty line
+  // of stdout). Surface it so the caller has the comment URL without a re-read.
+  const commentUrl = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .pop() ?? null;
+  if (commentUrl === null || !/^https?:\/\//u.test(commentUrl)) {
+    throw new Error(`gh issue comment did not return a comment URL (got: ${result.stdout.trim() || "<empty>"})`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, commentUrl };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseCommentIssueCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await commentIssue(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}