@sun-asterisk/sungen 3.2.24-beta.2 → 3.2.24-beta.3

package/src/cli/commands/depth-lint.ts

@@ -3,16 +3,8 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runDepthLint, renderDepthLint } from '../../harness/depth-lint';
 import { reportSlug } from '../../harness/unit-paths';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 export function registerDepthLintCommand(program: Command): void {
   program
@@ -24,7 +16,7 @@ export function registerDepthLintCommand(program: Command): void {
       try {
         const name = options.screen;
         if (!name) throw new Error('Provide --screen <name>');
-        const dir = findScreenDir(name);
+        const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name} or qa/flows/${name}`);
 
         const report = runDepthLint(dir, name);

package/src/cli/commands/gate.ts

@@ -2,16 +2,8 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runGate, renderGate, GatePhase } from '../../harness/journey';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
 
@@ -28,7 +20,7 @@ export function registerGateCommand(program: Command): void {
         if (!name) throw new Error('Provide --screen <name>');
         const phase = options.phase as GatePhase;
         if (!PHASES.includes(phase)) throw new Error(`Provide --phase <${PHASES.join('|')}>`);
-        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (!findUnitDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const verdict = runGate(process.cwd(), name, phase);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));

package/src/cli/commands/journey.ts

@@ -3,16 +3,8 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runJourney, waive, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard } from '../../harness/journey';
 import { reportSlug } from '../../harness/unit-paths';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 export function registerJourneyCommand(program: Command): void {
   program
@@ -41,7 +33,7 @@ export function registerJourneyCommand(program: Command): void {
 
         const name = options.screen;
         if (!name) throw new Error('Provide --screen <name> (or --all for the roll-up)');
-        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (!findUnitDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = options.waive
           ? waive(process.cwd(), name, options.waive, options.reason || '')

package/src/cli/commands/manifest.ts

@@ -2,14 +2,8 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { buildManifest, diffManifest, loadManifest, saveManifest } from '../../harness/manifest';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  for (const p of ['screens', 'flows', 'api']) {
-    const d = path.join(process.cwd(), 'qa', p, name);
-    if (fs.existsSync(d)) return d;
-  }
-  return null;
-}
 
 export function registerManifestCommand(program: Command): void {
   program
@@ -24,7 +18,7 @@ export function registerManifestCommand(program: Command): void {
       try {
         const name = options.screen || options.api || options.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
-        const dir = findScreenDir(name);
+        const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
         if (options.diff) {

package/src/cli/commands/next.ts

@@ -0,0 +1,96 @@
+/**
+ * `sungen next [unit]` — the hand-back every command ends with.
+ *
+ * The next step is derived from what the project HOLDS, not from which command just ran, so a
+ * session cannot lose the thread by finishing somewhere that has no footer of its own (#597).
+ */
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { readUnitState, UnitState } from '../../harness/next-step';
+import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+
+/** Every unit the project holds, so `sungen next` with no argument still answers. */
+function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
+  const out: Array<{ name: string; kind: UnitState['kind']; dir: string }> = [];
+  for (const [dir, kind] of [['screens', 'screen'], ['flows', 'flow'], ['api', 'api']] as const) {
+    const base = path.join(cwd, 'qa', dir);
+    try {
+      for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+        if (e.isDirectory()) out.push({ name: e.name, kind, dir: path.join(base, e.name) });
+      }
+    } catch { /* the project may not use this unit kind */ }
+  }
+  return out;
+}
+
+function render(s: UnitState): void {
+  const L = console.log;
+  L('');
+  L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
+  L('');
+  const held = [
+    s.hasSpec && 'spec', s.hasViewpoint && 'viewpoint',
+    s.kind === 'flow' && s.hasContract && (s.hasFlowInventory ? 'contract+inventory' : 'contract (phases only)'),
+    s.scenarioCount > 0 && `${s.scenarioCount} scenarios`,
+    s.hasSelectors && (s.selectorsArePlaceholder ? 'selectors (placeholder)' : 'selectors'),
+    s.compiled && 'compiled', s.hasResults && 'results', s.hasDeliverable && 'deliverable',
+  ].filter(Boolean);
+  L(`  state: ${held.length ? held.join(' · ') : '(nothing yet)'}`);
+  if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
+  L('');
+  for (const st of s.steps) {
+    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : '→';
+    L(`  ${mark} ${st.command}`);
+    L(`     ${st.because}`);
+  }
+  L('');
+}
+
+export function registerNextCommand(program: Command): void {
+  program
+    .command('next [unit]')
+    .description('What to do next for a unit (or every unit), derived from the project state')
+    .option('--json', 'Machine-readable output')
+    .action((unit: string | undefined, o: { json?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        let states: UnitState[];
+        if (unit) {
+          const resolved = resolveUnit(unit, cwd);
+          if (!resolved) {
+            console.error(`Error: no unit named "${unit}" under qa/screens, qa/flows or qa/api.`);
+            process.exit(1);
+          }
+          states = [readUnitState(cwd, resolved.dir, unit, resolved.kind)];
+        } else {
+          const units = allUnits(cwd);
+          if (units.length === 0) {
+            console.error('Error: this project holds no units yet — run `sungen add --screen <name> --path <url>` or `sungen add-flow --flow <name> --path <url>`.');
+            process.exit(1);
+          }
+          // A name in two places is ambiguous; report it rather than answering for one of them.
+          states = units.map((u) => {
+            if (resolveUnitCandidates(u.name, cwd).length > 1) throw new AmbiguousUnitError(u.name, resolveUnitCandidates(u.name, cwd));
+            return readUnitState(cwd, u.dir, u.name, u.kind);
+          });
+        }
+        if (o.json) {
+          console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
+          return;
+        }
+        for (const s of states) render(s);
+      } catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * The one-line hand-back every command prints last. Kept deliberately small: it points at the
+ * resolver instead of restating a next step, so no command can drift from the real state.
+ */
+export function printHandBack(unit?: string): void {
+  console.log(`Next: sungen next${unit ? ` ${unit}` : ''}`);
+}

package/src/cli/index.ts

@@ -27,6 +27,7 @@ import { registerFeedbackCommand } from './commands/feedback';
 import { registerQaFeedbackCommand } from './commands/qa-feedback';
 import { registerScriptCheckCommand } from './commands/script-check';
 import { registerTraceCommand } from './commands/trace';
+import { registerNextCommand } from './commands/next';
 import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
@@ -74,6 +75,7 @@ async function main() {
   registerQaFeedbackCommand(program);
   registerScriptCheckCommand(program);
   registerTraceCommand(program);
+  registerNextCommand(program);
   registerChallengeCommand(program);
   registerBlindspotCommand(program);
   registerCapabilityCommand(program);
@@ -96,6 +98,35 @@ async function main() {
   // say so (stderr, so `--json` output stays parseable).
   program.hook('preAction', () => { warnAssetsDrift(process.cwd()); });
 
+  // #597 — the hand-back, once, for EVERY command. It used to be hardcoded per command and only
+  // two of twenty-nine printed one, so a run that finished anywhere else finished in silence:
+  // `capability add` ended with a blank line and the session stopped mid-workflow. Adding a
+  // footer to the other twenty-seven would repeat the mistake in bulk.
+  //
+  // It hangs off `process.on('exit')` rather than a postAction hook because several commands
+  // exit with a MEANINGFUL code (`depth-lint` returns 2 when there are deepen candidates) and
+  // `process.exit` skips commander's hooks entirely — a postAction version printed for `audit`
+  // and silently not for `depth-lint`, which is the same class of gap all over again.
+  //
+  // It points at `sungen next` instead of restating a step, so it can never drift from the real
+  // project state. Skipped on a hard error (code 1): there the error message is the actionable
+  // thing, and burying it under a footer helps nobody. `--json` keeps stdout parseable.
+  let handBack: { unit?: string; json: boolean } | null = null;
+  program.hook('preAction', (_thisCommand, actionCommand) => {
+    if (actionCommand.name() === 'next') return;            // `next` IS the answer
+    const opts = actionCommand.opts() as Record<string, unknown>;
+    const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
+      ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
+    handBack = { unit: unit as string | undefined, json: opts.json === true };
+  });
+  process.on('exit', (code) => {
+    if (!handBack || code === 1) return;
+    const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
+    // stderr under --json so the hand-back never lands in the parsed payload.
+    if (handBack.json) process.stderr.write(`${line}\n`);
+    else process.stdout.write(`${line}\n`);
+  });
+
   await program.parseAsync(process.argv);
 }
 

package/src/cli/resolve-unit.ts

@@ -0,0 +1,72 @@
+/**
+ * One resolver for "which unit does this name mean?", shared by every command.
+ *
+ * Seven commands each had their own copy, and all seven searched `qa/screens/` FIRST. So a
+ * directory at `qa/screens/<name>/` SHADOWED a real flow of the same name — and the failure was
+ * silent, not loud: `sungen audit` resolved to the phantom screen, found no feature file, and
+ * reported 0 scenarios with no contract and no scored axis. A run that dropped the entire quality
+ * gate looked like a suite with nothing in it.
+ *
+ * That shape is not hypothetical: the mock driver resolves its catalog from
+ * `qa/screens/<unit>/mock/mocks.yaml` only, so making a mock work for a flow means creating
+ * exactly that phantom directory (#597).
+ *
+ * A name resolving to two units is ambiguous, and ambiguity is reported rather than resolved by
+ * search order.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+
+const KINDS: Array<{ kind: UnitKind; dir: string }> = [
+  { kind: 'screen', dir: 'screens' },
+  { kind: 'flow', dir: 'flows' },
+  { kind: 'api', dir: 'api' },       // qa/api/<area> or qa/api/flows/<flow>
+];
+
+export interface ResolvedUnit {
+  dir: string;
+  kind: UnitKind;
+  /** Catalog unit id relative to qa/: `<screen>` · `flows/<f>` · `api/<a>` · `api/flows/<f>`. */
+  unitId: string;
+}
+
+/** Every unit directory this name matches, in `screens, flows, api` order. */
+export function resolveUnitCandidates(name: string, cwd = process.cwd()): ResolvedUnit[] {
+  const out: ResolvedUnit[] = [];
+  for (const { kind, dir } of KINDS) {
+    const p = path.join(cwd, 'qa', dir, name);
+    if (!fs.existsSync(p)) continue;
+    out.push({ dir: p, kind, unitId: kind === 'screen' ? name : `${dir}/${name}` });
+  }
+  return out;
+}
+
+export class AmbiguousUnitError extends Error {
+  constructor(public readonly name: string, public readonly candidates: ResolvedUnit[]) {
+    super(
+      `"${name}" names ${candidates.length} units: ${candidates.map((c) => `qa/${c.kind === 'screen' ? 'screens/' : ''}${c.unitId}`).join(' and ')}.\n`
+      + '  Resolving this by search order silently picks one and drops the other unit\'s feature,\n'
+      + '  contract and scored axes — a report with 0 scenarios rather than an error. Rename one,\n'
+      + '  or remove the directory that should not exist (a stray `qa/screens/<flow-name>/`\n'
+      + '  created to satisfy a screen-only driver is the usual cause).',
+    );
+    this.name = 'AmbiguousUnitError';
+  }
+}
+
+/**
+ * The single unit this name means. Throws `AmbiguousUnitError` when several match; returns null
+ * when none do (callers report "unit not found" with their own guidance).
+ */
+export function resolveUnit(name: string, cwd = process.cwd()): ResolvedUnit | null {
+  const found = resolveUnitCandidates(name, cwd);
+  if (found.length > 1) throw new AmbiguousUnitError(name, found);
+  return found[0] ?? null;
+}
+
+/** Back-compat shape for the callers that only want the directory. */
+export function findUnitDir(name: string, cwd = process.cwd()): string | null {
+  return resolveUnit(name, cwd)?.dir ?? null;
+}

package/src/harness/audit.ts

@@ -586,11 +586,19 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // TQ-10 — surface the Capability Planner recommendation (recommend-only; never installs). Silenced
   // by `capability_suggestions: off` in qa/context.md. Reuses the planner (trustworthy after TQ-9).
   if (intent.capabilitySuggestions) {
-    const plan = buildPlan(screenDir, screenName);
+    // The catalog unit id (`flows/<f>`, `api/<a>`) carries the unit KIND, which gates which
+    // drivers can serve it at all.
+    const plan = buildPlan(screenDir, screenName, catalogScreenName);
     if (plan.recommendations.length) {
       const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
       findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);
     }
+    // Named, not dropped: without this the scenarios read as "nothing could help", and the
+    // operator's only clue was an install that dead-ends (#597).
+    if (plan.unavailable.length) {
+      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count})`).join(' · ');
+      findings.push(`CAPABILITY-UNAVAILABLE: ${un} — ${plan.unavailable.length === 1 ? 'that driver does' : 'those drivers do'} not support a ${plan.unavailable[0].unitKind} unit, so ${plan.unavailable.length === 1 ? 'it' : 'they'} cannot automate these scenarios here. Do NOT install: the scenarios stay @manual until the driver gains ${plan.unavailable[0].unitKind} support. Automating the same behaviour on the owning SCREEN unit is the available route today.`);
+    }
   }
   // TQ-11b — automation-ready (pending capability): @requires:<cap> scenarios whose cap isn't enabled.
   // They are NOT manual (real steps, compiled the moment the cap is added) — surface them distinctly.

package/src/harness/capability-plan.ts

@@ -8,7 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadDriverCatalog } from './capability';
+import { loadDriverCatalog, unitKindOf, driverServesUnit } from './capability';
 import { readTextFile } from './read-text';
 import { featureFilesFor } from './unit-paths';
 
@@ -190,12 +190,21 @@ export interface CapabilityPlan {
   crossScreen: number;            // automatable via a flow — not a single-screen driver gap
   capabilityManualPct: number;
   recommendations: { driver: string; pkg: string; reason: string; count: number; scenarios: string[] }[];
+  /**
+   * Drivers that WOULD have been recommended but cannot serve this unit kind. Surfaced, never
+   * dropped: the scenarios stay manual for a reason the operator needs to know, and a silent
+   * omission would read as "nothing could help here" (#597).
+   */
+  unavailable: { driver: string; reason: string; count: number; unitKind: string }[];
   keep: { code: string; count: number }[];
 }
 
-export function buildPlan(screenDir: string, screenName: string): CapabilityPlan {
+export function buildPlan(screenDir: string, screenName: string, unitId = screenName): CapabilityPlan {
   const scenarios = featureFilesFor(screenDir, screenName).flatMap(parseScenarios);
   const catalog = loadDriverCatalog();
+  // Recommending a driver that cannot serve this unit KIND costs an install, a dead end and a
+  // manual rollback — which is exactly what the mock driver (screen-only) did on a flow (#597).
+  const unitKind = unitKindOf(unitId);
 
   const modes: Record<string, number> = {};
   const byReason: Record<string, number> = {};
@@ -230,7 +239,17 @@ export function buildPlan(screenDir: string, screenName: string): CapabilityPlan
     }
   }
 
-  const recommendations = [...recByDriver.entries()]
+  const servable = [...recByDriver.entries()].filter(([d]) => driverServesUnit(d, unitKind));
+  const unavailable = [...recByDriver.entries()]
+    .filter(([d]) => !driverServesUnit(d, unitKind))
+    .map(([driver, v]) => ({
+      driver,
+      reason: v.reason,
+      count: v.scenarios.length,
+      unitKind,
+    }))
+    .sort((a, b) => b.count - a.count);
+  const recommendations = servable
     .map(([driver, v]) => ({
       driver,
       pkg: catalog[driver]?.package || `@sungen/driver-${driver}`,
@@ -252,6 +271,7 @@ export function buildPlan(screenDir: string, screenName: string): CapabilityPlan
     crossScreen,
     capabilityManualPct: manualTotal ? Math.round((capabilityManual / manualTotal) * 100) : 0,
     recommendations,
+    unavailable,
     keep: Object.entries(keepCount).map(([code, count]) => ({ code, count })).sort((a, b) => b.count - a.count),
   };
 }

package/src/harness/capability.ts

@@ -73,6 +73,28 @@ export interface DriverMeta {
   bundled?: boolean;       // shipped as a core dependency — present without `capability add`
   capabilities: string[];
   unblocks?: string[];
+  /**
+   * Unit kinds this driver can actually serve. Absent = all kinds.
+   *
+   * A driver that only resolves its config from one unit shape must say so, or the capability
+   * planner recommends it for a unit it can never serve — which is what happened with the mock
+   * driver on a flow: install, dead end, manual rollback (#597).
+   */
+  units?: Array<'screen' | 'flow' | 'api'>;
+}
+
+/** The unit kind of a catalog unit id: `flows/<f>` → flow, `api/<a>` → api, else screen. */
+export function unitKindOf(catalogUnitId: string): 'screen' | 'flow' | 'api' {
+  const seg = catalogUnitId.split('/')[0];
+  if (seg === 'api') return 'api';
+  if (seg === 'flows') return 'flow';
+  return 'screen';
+}
+
+/** Can this driver serve that unit kind? Unknown driver → assume yes (nothing to gate on). */
+export function driverServesUnit(driverId: string, kind: 'screen' | 'flow' | 'api'): boolean {
+  const units = driverMeta(driverId)?.units;
+  return !units || units.includes(kind);
 }
 
 export function capabilitiesPath(cwd: string): string {

package/src/harness/catalog/drivers.yaml

@@ -61,6 +61,11 @@ drivers:
     status: shipped
     capabilities: ["@mock", "@network"]
     unblocks: [M3]
+    # `units:` is the unit KINDS this driver can actually serve. Absent → all kinds.
+    # The mock driver resolves its catalog from qa/screens/<unit>/mock/mocks.yaml only
+    # (mockCatalogPath is hardcoded to that shape), so it cannot serve a flow. Recommending
+    # it for one sent an operator through an install, a dead end and a manual rollback (#597).
+    units: [screen]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"