@playcraft/cli 0.1.36-beta1 → 0.1.38-beta

package/project-template-v2/skills/_shared/scripts/state-get.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * Read project state from docs/project-state.json.
+ *
+ * Outputs two views:
+ *   - Orchestrator view (default): pipeline, stageExit, dispatchableRoles,
+ *     canWriteTodo, todo pool summary, todosCleared, gate, recent handoff history tail.
+ *   - Subagent view (--json dispatch): just state.dispatch (the workticket).
+ *     Must NOT include exit/dispatchableRoles.
+ *
+ * Usage:
+ *   npm run state:get
+ *   node skills/_shared/scripts/state-get.mjs --root=. --json dispatch
+ *   node skills/_shared/scripts/state-get.mjs --root=. iteration stage
+ */
+
+import {
+  flatHandoff,
+  readState,
+  stateExists,
+  todosCleared,
+} from './state-store.mjs';
+import {
+  specForIteration,
+  stageConfig,
+  dispatchableRoles,
+  canWriteTodo,
+  stageExit,
+  subagentFieldsForStage,
+  STAGES,
+  dodKeysForStage,
+  dodDefinition,
+  routeForFailedDoDKeys,
+} from './pipeline/index.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), keys: [], json: false, jsonTarget: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--root=')) {
+      opts.root = arg.slice('--root='.length);
+    } else if (arg === '--json') {
+      opts.json = true;
+      // Check if next arg is a target (not a flag)
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        opts.jsonTarget = argv[++i];
+      }
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: state-get.mjs [--root=.] [--json [dispatch|orchestrator]] [key ...]');
+      console.log('  --json dispatch     Emit only state.dispatch (subagent workticket)');
+      console.log('  --json              Emit full orchestrator view as JSON');
+      process.exit(0);
+    } else if (!arg.startsWith('-')) {
+      opts.keys.push(arg);
+    }
+  }
+  return opts;
+}
+
+/** Summarize todo pool for the current iteration in orchestrator view. */
+function buildTodoSummary(todos, iteration) {
+  const currentIteration = Number(iteration) || 1;
+  const all = (todos || []).filter((t) => Number(t.iteration ?? currentIteration) === currentIteration);
+  const byStatus = { pending: [], in_progress: [], done: [], failed: [] };
+  for (const t of all) {
+    const bucket = byStatus[t.status] ?? (byStatus[t.status] = []);
+    bucket.push(t.id);
+  }
+  return {
+    total: all.length,
+    pending: byStatus.pending,
+    in_progress: byStatus.in_progress,
+    done: byStatus.done,
+    failed: byStatus.failed,
+    contextReuse: all
+      .filter((t) => t.contextReuse)
+      .map((t) => ({
+        id: t.id,
+        status: t.status,
+        key: t.contextReuse || '',
+      })),
+  };
+}
+
+function buildContextReuseHint(todos, iteration, stage, handoff) {
+  if (stage !== 'generate') return null;
+
+  const currentIteration = Number(iteration) || 1;
+  const all = (todos || []).filter((t) => Number(t.iteration ?? currentIteration) === currentIteration);
+  const nextPendingIndex = all.findIndex((t) => t.status === 'pending');
+  if (nextPendingIndex < 0) return null;
+
+  const candidate = all[nextPendingIndex];
+  const previous = nextPendingIndex > 0 ? all[nextPendingIndex - 1] : null;
+  const limit = 3;
+  const recent = handoff?.history?.length ? handoff.history[handoff.history.length - 1] : null;
+  const blockers = Array.isArray(recent?.blockers) ? recent.blockers : [];
+
+  const base = {
+    nextTodoId: candidate.id,
+    reusable: Boolean(candidate.contextReuse),
+    key: candidate.contextReuse || '',
+    limit,
+    eligibleForSendMessage: false,
+    reason: '',
+  };
+
+  if (!candidate.contextReuse) return { ...base, reason: 'next todo has no contextReuse' };
+  if (!previous) return { ...base, reason: 'next todo has no previous contiguous todo' };
+  if (previous.status !== 'done') return { ...base, reason: 'previous contiguous todo is not done' };
+  if (!previous.contextReuse || previous.contextReuse !== candidate.contextReuse) {
+    return { ...base, reason: 'previous contiguous todo has different reuse key' };
+  }
+  if (!recent) return { ...base, reason: 'no latest handoff to resume with sendMessage' };
+  if (recent.role !== candidate.role) {
+    return { ...base, reason: 'latest handoff role does not match next todo role' };
+  }
+  if (blockers.length > 0) return { ...base, reason: 'latest handoff has blockers' };
+
+  let contiguousCount = 1;
+  for (let idx = nextPendingIndex - 1; idx >= 0; idx -= 1) {
+    const todo = all[idx];
+    if (
+      todo.status !== 'done'
+      || !todo.contextReuse
+      || todo.contextReuse !== candidate.contextReuse
+      || todo.role !== candidate.role
+    ) {
+      break;
+    }
+    contiguousCount += 1;
+  }
+
+  if (contiguousCount > limit) {
+    return {
+      ...base,
+      contiguousCount,
+      reason: `contiguous reusable run ${contiguousCount} exceeds limit ${limit}`,
+    };
+  }
+
+  return {
+    ...base,
+    contiguousCount,
+    previousTodoId: previous.id,
+    eligibleForSendMessage: true,
+    reason: 'same role, contiguous done todo, same reuse key, within limit, no blocker',
+  };
+}
+
+function isRealTodoId(id) {
+  return id && id !== 'none' && !id.startsWith('stage:');
+}
+
+function findTodoForDispatch(state) {
+  const id = state.dispatch?.activeTodoId;
+  if (!isRealTodoId(id)) return null;
+  return (state.todos || []).find((t) => t.id === id && t.iteration === state.pipeline.iteration)
+    ?? (state.todos || []).find((t) => t.id === id)
+    ?? null;
+}
+
+function buildDispatchView(state) {
+  const dispatch = state.dispatch || {};
+  const todo = findTodoForDispatch(state);
+  if (!todo) return dispatch;
+
+  return {
+    activeTodoId: dispatch.activeTodoId || todo.id,
+    role: dispatch.role || todo.role,
+    title: todo.title || todo.id,
+    goal: dispatch.goal || todo.goal || todo.title || '',
+    context: todo.context || '',
+    guidance: dispatch.guidance || '',
+    skillHints: dispatch.skillHints || [],
+    requiredContext: dispatch.requiredContext?.length ? dispatch.requiredContext : todo.requiredContext || [],
+    contextReuse: dispatch.contextReuse || todo.contextReuse || '',
+    allowedFiles: dispatch.allowedFiles || [],
+    forbiddenTasks: dispatch.forbiddenTasks || [],
+    acceptance: dispatch.acceptance?.length ? dispatch.acceptance : todo.acceptance || [],
+    verifier: dispatch.verifier || todo.verifier || '',
+  };
+}
+
+function omitEmptyDispatchFields(dispatch) {
+  const out = {};
+  for (const [key, value] of Object.entries(dispatch || {})) {
+    if (value === '') continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Build stageDod summary for orchestrator view. */
+function buildStageDod(iteration, stage, stageDoD) {
+  const keys = dodKeysForStage(iteration, stage);
+  if (!keys.length) return null;
+
+  const current = stageDoD || {};
+  const pending = keys.filter((k) => !current[k]);
+  const passed = keys.filter((k) => current[k] === true || current[k] === 'passed' || current[k] === 'pass');
+  const failed = keys.filter((k) => current[k] === false || current[k] === 'failed' || current[k] === 'fail');
+
+  const scripts = {};
+  const routing = {};
+  for (const k of keys) {
+    const def = dodDefinition(k);
+    if (def?.script) scripts[k] = def.script;
+    routing[k] = { routeTo: def?.routeTo ?? 'developer', nextAction: def?.nextAction ?? '' };
+  }
+
+  const failRoute = failed.length ? routeForFailedDoDKeys(failed) : null;
+
+  return { keys, scripts, pending, passed, failed, routing, failRoute };
+}
+
+function buildOrchestratorAction(dispatch, pendingUserInput) {
+  if (
+    dispatch?.activeTodoId
+    && dispatch.activeTodoId !== 'none'
+    && pendingUserInput?.status === 'awaiting_user_input'
+  ) {
+    return 'ask_user_then_sendMessage_to_active_subagent';
+  }
+  if (
+    dispatch?.activeTodoId
+    && dispatch.activeTodoId !== 'none'
+    && pendingUserInput?.status === 'answered'
+  ) {
+    return 'sendMessage_answer_to_active_subagent';
+  }
+  if (dispatch?.activeTodoId && dispatch.activeTodoId !== 'none') {
+    return 'resume_active_dispatch';
+  }
+  return 'select_next_dispatch_or_stage_action';
+}
+
+/** Build orchestrator view. */
+function buildOrchestratorView(state) {
+  const { pipeline, todos, gate, handoff, dispatch, devPreview } = state;
+  const iteration = pipeline.iteration;
+  const stage = pipeline.stage;
+
+  const exitStr = stageExit(iteration, stage);
+  const roles = dispatchableRoles(iteration, stage);
+  const todoWriteRoles = canWriteTodo(iteration, stage);
+  const cleared = todosCleared(state);
+  const todoSummary = buildTodoSummary(todos, iteration);
+
+  // recent handoff history tail (last 3)
+  const history = handoff.history || [];
+  const recentHistory = history.slice(-3).map((e) => ({
+    seq: e.seq,
+    role: e.role,
+    stage: e.stage,
+    status: e.status,
+    summary: e.summary,
+    artifactRefs: e.artifactRefs,
+    pendingUserInput: e.pendingUserInput?.status && e.pendingUserInput.status !== 'none'
+      ? e.pendingUserInput
+      : null,
+  }));
+
+  return {
+    // 主线指针
+    pipeline: {
+      iteration: pipeline.iteration,
+      stage: pipeline.stage,
+      stageStatus: pipeline.stageStatus,
+      userConfirm: pipeline.userConfirm,
+    },
+    // 退出条件(只给调度者,不给 subagent)
+    stageExit: exitStr,
+    // 调度者可派角色
+    dispatchableRoles: roles,
+    // todo 写权限角色
+    canWriteTodo: todoWriteRoles,
+    // todo 池摘要
+    todoPool: todoSummary,
+    todosCleared: cleared,
+    // 闸门
+    gate: gate,
+    // 用户输入等待态:dispatch 仍 active,调度者问用户后用 sendMessage 恢复同一个 subagent
+    pendingUserInput: handoff.pendingUserInput || null,
+    orchestratorAction: buildOrchestratorAction(dispatch, handoff.pendingUserInput),
+    contextReuseHint: buildContextReuseHint(todos, iteration, stage, handoff),
+    // 最近 handoff 轨
+    recentHandoffHistory: recentHistory,
+    // 共享决策
+    sharedDecisions: handoff.sharedDecisions || {},
+    // dev server 状态
+    devStatus: devPreview?.devStatus ?? null,
+    devUrl: devPreview?.devUrl ?? null,
+    loadCheck: devPreview?.loadCheck ?? null,
+    // 当前 dispatch(调度者写的工单摘要)
+    activeTodoId: dispatch?.activeTodoId ?? 'none',
+    dispatchedRole: dispatch?.role ?? '',
+    // DoD 检查（只在有定义的阶段非 null）
+    stageDod: buildStageDod(iteration, stage, gate?.stageDoD),
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!stateExists(opts.root)) {
+    console.error('Missing docs/project-state.json (run npm run ensure:project)');
+    process.exit(1);
+  }
+  const state = readState(opts.root);
+
+  // Subagent dispatch view: only state.dispatch, nothing else
+  if (opts.jsonTarget === 'dispatch' || (opts.json && opts.jsonTarget === 'dispatch')) {
+    console.log(JSON.stringify(omitEmptyDispatchFields(buildDispatchView(state)), null, 2));
+    return;
+  }
+
+  const view = buildOrchestratorView(state);
+
+  if (opts.json) {
+    // Full JSON orchestrator view, optionally filtered by keys
+    const keys = opts.keys.length > 0 ? opts.keys : Object.keys(view);
+    const out = {};
+    for (const key of keys) {
+      out[key] = view[key] ?? null;
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  // Text output
+  const keys = opts.keys.length > 0 ? opts.keys : Object.keys(view);
+  for (const key of keys) {
+    const value = view[key];
+    console.log(`${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+  }
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/state-handoff.mjs

@@ -0,0 +1,39 @@
+/**
+ * state-handoff — thin façade over state-store for hooks/callers that only need
+ * the flat handoff map.
+ *
+ * Process backing file is docs/project-state.json; the md is a rendered, read-only
+ * view. Hooks read state via flatHandoff; they never parse the md. This module
+ * exists so read-only hooks and dev-start can import a stable, store-backed API
+ * instead of touching state-store internals directly.
+ */
+
+import path from 'node:path';
+import { applyStateUpdates, flatHandoff, readState } from './state-store.mjs';
+
+export function resolveProjectStatePath(root) {
+  return path.join(path.resolve(root), 'docs/project-state.md');
+}
+
+/** Derive the project root from a docs/project-state.md path. */
+function rootFromStatePath(statePath) {
+  // statePath = <root>/docs/project-state.md
+  return path.dirname(path.dirname(path.resolve(statePath)));
+}
+
+/**
+ * Apply flat key/value updates through the store (JSON truth + rendered md).
+ * Takes the md path; resolves the project root from it internally.
+ * @param {string} statePath path to docs/project-state.md
+ * @param {Record<string, string>} updates
+ * @returns {object} flattened handoff view
+ */
+export function applyHandoffUpdates(statePath, updates) {
+  const state = applyStateUpdates(rootFromStatePath(statePath), updates);
+  return flatHandoff(state);
+}
+
+/** Read the flat handoff view (pipeline+dispatch+todos+gate) for a project root. */
+export function readHandoffForRoot(root) {
+  return flatHandoff(readState(root));
+}

package/project-template-v2/skills/_shared/scripts/state-set.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Update project state without hand-editing markdown.
+ *
+ * Writes into docs/project-state.json (process backing file) and re-renders
+ * docs/project-state.md. Keys are routed to the right section automatically.
+ *
+ * Usage:
+ *   npm run state:set -- stage=generate stageStatus=in_progress
+ *   npm run state:set -- devStatus=ready
+ *   npm run state:set -- canAskUser=yes
+ *   npm run state:set -- pipelinePatch='{"userConfirm":"confirmed"}'
+ *   npm run state:set -- dispatchPatch='{"role":"developer","goal":"..."}'
+ *   node skills/_shared/scripts/state-set.mjs --root=. key=value [...]
+ *
+ * Flat keys:
+ *   iteration, stage, stageStatus, userConfirm → pipeline.*
+ *   canAskUser → gate.canAskUser
+ *   devPreview keys (devStatus, devUrl, loadCheck, etc.)
+ *   userIntent
+ * JSON-patch keys (merge):
+ *   pipelinePatch, dispatchPatch, handoffPatch, pendingUserInputPatch,
+ *   sharedDecisionsPatch, gatePatch
+ * Array-replace key:
+ *   todosPatch (JSON array)
+ */
+
+import {
+  applyStateUpdates,
+  readState,
+} from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), pairs: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--root=')) {
+      opts.root = arg.slice('--root='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: state-set.mjs [--root=.] key=value [...]');
+      console.log('Flat keys: iteration, stage, stageStatus, userConfirm, canAskUser, userIntent, devStatus, devUrl, loadCheck, ...');
+      console.log('JSON-patch keys: pipelinePatch, dispatchPatch, handoffPatch, pendingUserInputPatch, sharedDecisionsPatch, gatePatch, todosPatch');
+      process.exit(0);
+    } else if (arg.includes('=')) {
+      const eq = arg.indexOf('=');
+      opts.pairs.push({ key: arg.slice(0, eq), value: arg.slice(eq + 1) });
+    }
+  }
+  return opts;
+}
+
+function flattenForPrint(state) {
+  return {
+    // pipeline fields
+    iteration: state.pipeline?.iteration,
+    stage: state.pipeline?.stage,
+    stageStatus: state.pipeline?.stageStatus,
+    userConfirm: state.pipeline?.userConfirm,
+    // gate
+    canAskUser: state.gate?.canAskUser,
+    // top-level
+    userIntent: state.userIntent,
+    // devPreview
+    ...state.devPreview,
+    devBlockers: JSON.stringify(state.devPreview?.devBlockers ?? []),
+    // dispatch summary
+    dispatch: JSON.stringify(state.dispatch || {}),
+    pendingUserInput: JSON.stringify(state.handoff?.pendingUserInput || {}),
+    pendingUserInputPatch: JSON.stringify(state.handoff?.pendingUserInput || {}),
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.pairs.length === 0) {
+    console.error('Nothing to set. Example: npm run state:set -- stage=generate');
+    process.exit(1);
+  }
+
+  const updates = {};
+  for (const { key, value } of opts.pairs) {
+    updates[key] = value;
+  }
+  applyStateUpdates(opts.root, updates);
+
+  const printable = flattenForPrint(readState(opts.root));
+  for (const { key } of opts.pairs) {
+    const v = printable[key];
+    console.log(`${key}: ${v != null ? v : ''}`);
+  }
+}
+
+main();