@sun-asterisk/sungen 3.2.3 → 3.2.5

package/dist/tools/sungen-auth/sungen-auth-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared types for the sungen CLI login flow (RFC 8252 native-app login against
+ * a FastSchema v0.13.0 backend: PKCE-S256 + loopback redirect + one-time code).
+ */
+/** Persisted, user-level credentials at ~/.sungen/credentials.json (mode 0600). */
+export interface Credentials {
+    /** Bearer JWT minted by the backend exchange step. */
+    token: string;
+    /** Authenticated account email (from /api/auth/me). */
+    email: string;
+    /** Backend base URL the token was issued against (so `feedback` knows where to POST). */
+    api_base_url: string;
+    /** Unix epoch seconds when the token expires, if the backend reports it (single token, no refresh). */
+    expires_at?: number;
+}
+/** Response of POST /api/auth/cli/initiate (unwrapped from the {data} envelope). */
+export interface InitiateResponse {
+    /** Signed carrier the dashboard login page consumes. */
+    carrier: string;
+    /** Path (not absolute) to open in the browser, e.g. /dash/login?cli=<carrier>. */
+    authorize_url: string;
+}
+/** Response of POST /api/auth/exchange (unwrapped from the {data} envelope). */
+export interface ExchangeResponse {
+    /** Bearer JWT. */
+    token: string;
+    /** ISO expiry string the backend returns (e.g. "2026-07-08T06:42:30Z"). */
+    expires?: string;
+    /** Numeric epoch-seconds expiry, if a build reports it instead. */
+    expires_at?: number;
+}
+/** Response of GET /api/auth/me (subset we rely on, unwrapped from {data}). */
+export interface MeResponse {
+    email: string;
+}
+/** PKCE material generated per login attempt; never persisted to disk. */
+export interface PkceMaterial {
+    verifier: string;
+    challenge: string;
+}
+//# sourceMappingURL=sungen-auth-types.d.ts.map

package/dist/tools/sungen-auth/sungen-auth-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sungen-auth-types.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-auth/sungen-auth-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/tools/sungen-auth/sungen-auth-types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Shared types for the sungen CLI login flow (RFC 8252 native-app login against
+ * a FastSchema v0.13.0 backend: PKCE-S256 + loopback redirect + one-time code).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sungen-auth-types.js.map

package/dist/tools/sungen-auth/sungen-auth-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sungen-auth-types.js","sourceRoot":"","sources":["../../../src/tools/sungen-auth/sungen-auth-types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.3",
+  "version": "3.2.5",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.3",
+    "@sungen/driver-ui": "3.2.5",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
@@ -47,6 +47,7 @@
     "fast-glob": "^3.3.3",
     "glob": "^13.0.0",
     "handlebars": "^4.7.8",
+    "jszip": "^3.10.1",
     "ora": "^9.0.0",
     "plop": "^4.0.4",
     "tsx": "^4.22.4",

package/src/cli/commands/dashboard.ts

@@ -82,12 +82,12 @@ export function registerDashboardCommand(program: Command): void {
         } else {
           targets = listDashboardTargets(cwd);
           if (targets.length === 0) {
-            console.error(`${COLOR.red}No screens or flows found in qa/screens/ or qa/flows/${COLOR.reset}`);
+            console.error(`${COLOR.red}No units found in qa/screens/, qa/flows/, or qa/api/${COLOR.reset}`);
             process.exit(1);
           }
         }
 
-        const labels = targets.map((t) => t.isFlow ? `flow/${t.name}` : t.name);
+        const labels = targets.map((t) => t.kind === 'flow' ? `flow/${t.name}` : t.kind === 'api' ? `api/${t.name}` : t.name);
         log(`${COLOR.bold}sungen dashboard${COLOR.reset} — building report for ${targets.length} target(s): ${labels.join(', ')}`);
 
         // 2. Build snapshot

package/src/cli/commands/delivery.ts

@@ -137,18 +137,30 @@ function qaDir(cwd: string, target: DeliveryTarget): string {
 }
 
 /**
- * Load the apis.yaml catalog for an api-kind unit.
- * The catalog lives at qa/api/<screen>/api/apis.yaml.
- * Returns an empty object when the file is absent (allows graceful degradation).
+ * Load the apis.yaml catalog for an api-kind unit, merging the shared catalog under
+ * the unit catalog. The runtime resolves an endpoint unit-scope-first then falls back
+ * to the shared catalog (driver-api api-catalog.ts), so an endpoint defined only in
+ * `qa/api/apis.yaml` still runs — we must load it too, or its request block would come
+ * back empty (the very bug this feature fixes). Unit wins on a name collision.
+ * Returns an empty object when neither file is present (graceful degradation).
  */
 function loadApiCatalog(cwd: string, target: DeliveryTarget): Record<string, ApiCatalogEntry> {
   if (target.kind !== 'api') return {};
-  const catalogPath = path.join(cwd, 'qa', 'api', target.screen, 'api', 'apis.yaml');
+  const shared = readApiCatalogFile(path.join(cwd, 'qa', 'api', 'apis.yaml'));
+  const unit = readApiCatalogFile(path.join(cwd, 'qa', 'api', target.screen, 'api', 'apis.yaml'));
+  return { ...shared, ...unit };
+}
+
+/** Parse one apis.yaml file into an endpoint map, unwrapping the optional `apis:` wrapper. */
+function readApiCatalogFile(catalogPath: string): Record<string, ApiCatalogEntry> {
   if (!fs.existsSync(catalogPath)) return {};
   try {
-    const parsed = parseYaml(fs.readFileSync(catalogPath, 'utf-8'));
+    const parsed = parseYaml(fs.readFileSync(catalogPath, 'utf-8')) as Record<string, unknown> | null;
     if (parsed && typeof parsed === 'object') {
-      return parsed as Record<string, ApiCatalogEntry>;
+      // The runtime loader accepts both a flat map and an `apis:` wrapper — unwrap it
+      // here too so both loaders read the same file identically.
+      const root = parsed.apis && typeof parsed.apis === 'object' ? parsed.apis : parsed;
+      return root as Record<string, ApiCatalogEntry>;
     }
   } catch { /* malformed yaml — skip */ }
   return {};
@@ -489,6 +501,8 @@ async function exportTarget(
         results: resolveResultsPath(cwd, target) ? loadPlaywrightReport(resolveResultsPath(cwd, target)!) : null,
         env,
         selectorKeyMap,
+        kind: target.kind,
+        apiCatalog,
       });
       const tempSummary = buildSummary(label, rows, '');
       const csv = renderCsv(tempSummary, rows, specLink);
@@ -533,6 +547,8 @@ async function exportTarget(
             results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
             env,
             selectorKeyMap,
+            kind: target.kind,
+            apiCatalog,
           });
           const csv = renderCsv(buildSummary(label, variantRows, ''), variantRows, specLink);
           const csvPath = writeCsv(cwd, target.featureBaseName, csv, variant.locale);
@@ -580,6 +596,8 @@ async function exportTarget(
         results: variantResults,
         env,
         selectorKeyMap,
+        kind: target.kind,
+        apiCatalog,
       });
 
       // CSV: always one file per locale, every row (CSV has no sheet concept).

package/src/cli/commands/feedback.ts

@@ -1,62 +1,134 @@
+/**
+ * `sungen feedback "<content>"` — submit PRODUCT feedback to the remote backend.
+ *
+ * One markdown record per call. Content comes from the positional arg, piped
+ * stdin, or — when run bare in a TTY — an $EDITOR session. Login-gated:
+ * missing/expired token prompts an interactive login. The author (created_by)
+ * is NEVER sent; the backend stamps it from the bearer token.
+ *
+ * NOTE: distinct from `sungen qa-feedback` (commands/qa-feedback.ts) — that writes
+ * the LOCAL QA-feedback log and is what the /sungen:feedback slash command calls.
+ */
+
 import { Command } from 'commander';
-import { recordFeedback, summarize, FeedbackType, FeedbackDecision } from '../../harness/feedback';
+import * as readline from 'readline';
+import { loadCredentials, isExpired } from '../../tools/sungen-auth/credentials-store';
+import { resolveApiBaseUrl } from '../../tools/sungen-auth/api-base-url';
+import { performLogin } from './login';
+import { submitFeedback, AuthExpiredError, FeedbackPayload } from '../../tools/sungen-api/feedback-client';
+import { readStdin } from '../../tools/sungen-api/read-stdin';
+import { composeInEditor } from '../../tools/sungen-api/edit-in-editor';
 
-const TYPES = ['test-design', 'product', 'other'];
-const DECISIONS = ['accept', 'reject', 'edit', 'add', 'none'];
+const CATEGORIES = ['quality', 'feature_request', 'bug', 'other'];
+const QA_WORDS = ['record', 'list'];
+const MAX_CONTENT_LEN = 10_000;
 
-export function registerFeedbackCommand(program: Command): void {
-  const fb = program
-    .command('feedback')
-    .description('Local-first QA feedback (test-design knowledge + product telemetry). Synced later when a server exists.');
+// CLI version → sungen_version; same source as cli/index.ts so it never drifts.
+const { version: SUNGEN_VERSION } = require('../../../package.json') as { version: string };
 
-  fb
-    .command('record')
-    .description('Record a feedback entry')
-    .requiredOption('--message <text>', 'The feedback')
-    .option('--type <t>', `Feedback type (${TYPES.join('|')})`, 'test-design')
-    .option('-s, --screen <name>', 'Screen/flow the feedback relates to')
-    .option('--target <ref>', 'What it is about (viewpoint id / scenario / command / artifact)')
-    .option('--decision <d>', `QA decision (${DECISIONS.join('|')})`, 'none')
-    .option('--reason <text>', 'Why')
-    .option('--source <who>', 'Who gave the feedback', 'qa')
-    .action((o) => {
-      try {
-        if (!TYPES.includes(o.type)) throw new Error(`--type must be one of ${TYPES.join(', ')}`);
-        if (!DECISIONS.includes(o.decision)) throw new Error(`--decision must be one of ${DECISIONS.join(', ')}`);
-        const p = recordFeedback({
-          type: o.type as FeedbackType,
-          screen: o.screen,
-          target: o.target,
-          decision: o.decision as FeedbackDecision,
-          message: o.message,
-          reason: o.reason,
-          source: o.source,
-        });
-        console.log(`✓ feedback recorded (${o.type}${o.screen ? ' · ' + o.screen : ''}) → ${p}`);
-      } catch (e) {
-        console.error('Error:', e instanceof Error ? e.message : e);
-        process.exit(1);
-      }
+/** Ask a yes/no question on the terminal; defaults to "no" on empty input. */
+function promptYesNo(question: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
     });
+  });
+}
+
+/** Resolve feedback content from positional arg or piped stdin. */
+async function resolveContent(positional?: string): Promise<string | null> {
+  if (positional && positional.trim()) return positional;
+  const piped = await readStdin();
+  if (piped && piped.trim()) return piped;
+  return null;
+}
+
+/** Ensure we have a valid token; prompt an interactive login if not. Returns creds or null if the user declines. */
+async function ensureLogin(apiBaseUrl: string): Promise<{ token: string; api_base_url: string } | null> {
+  const creds = loadCredentials();
+  if (creds && !isExpired(creds)) return creds;
+
+  const reason = creds ? 'Your session has expired.' : 'You are not logged in.';
+  const yes = await promptYesNo(`${reason} Log in now? (y/n) `);
+  if (!yes) return null;
+  return performLogin(apiBaseUrl);
+}
 
-  fb
-    .command('list')
-    .description('List / summarise recorded feedback')
-    .option('-s, --screen <name>', 'Filter by screen')
-    .option('--type <t>', 'Filter by type')
-    .option('--json', 'Output raw JSON')
-    .action((o) => {
+export function registerFeedbackCommand(program: Command): void {
+  program
+    .command('feedback [content]')
+    .description('Send product feedback about sungen (one record; pass as an argument, pipe via stdin, or run with no argument to compose in $EDITOR)')
+    .option('--category <c>', `Feedback category (${CATEGORIES.join('|')})`, 'other')
+    .option('--api-base-url <url>', 'Backend base URL (overrides SUNGEN_API_BASE_URL + stored value)')
+    .action(async (content: string | undefined, options: { category: string; apiBaseUrl?: string }) => {
       try {
-        const s = summarize({ screen: o.screen, type: o.type });
-        if (o.json) { console.log(JSON.stringify(s, null, 2)); return; }
-        console.log(`\n━━━ Feedback (${s.total}) ━━━`);
-        console.log(`  by type: ${Object.entries(s.byType).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}`);
-        console.log(`  by decision: ${Object.entries(s.byDecision).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}\n`);
-        for (const e of s.entries.slice(-20)) {
-          console.log(`  [${e.type}${e.decision && e.decision !== 'none' ? '/' + e.decision : ''}] ${e.screen ? e.screen + ' · ' : ''}${e.target ? e.target + ' — ' : ''}${e.message}`);
-          if (e.reason) console.log(`      reason: ${e.reason}`);
+        // Footgun guard: a bare `record`/`list` with no stdin is almost certainly
+        // someone reaching for the moved QA primitive, not real feedback text.
+        if (content && QA_WORDS.includes(content.trim()) && process.stdin.isTTY) {
+          console.error(
+            `The local QA log moved to \`sungen qa-feedback ${content.trim()}\`.\n` +
+            `To send "${content.trim()}" as product feedback, pipe it via stdin: echo "${content.trim()}" | sungen feedback`,
+          );
+          process.exit(1);
+        }
+
+        let text = await resolveContent(content);
+        if (!text) {
+          if (process.stdin.isTTY) {
+            // No arg and interactive: open the editor (like `git commit`).
+            text = composeInEditor();
+            if (!text) {
+              console.error('Aborting — no feedback provided (empty message).');
+              process.exit(1);
+            }
+          } else {
+            // Piped but empty.
+            console.error('Provide feedback text as an argument or pipe it via stdin.');
+            process.exit(1);
+          }
+        }
+        if (text.length > MAX_CONTENT_LEN) {
+          console.error(`Feedback is too long (${text.length} chars; max ${MAX_CONTENT_LEN}).`);
+          process.exit(1);
+        }
+
+        if (!CATEGORIES.includes(options.category)) {
+          console.error(`--category must be one of ${CATEGORIES.join(', ')}`);
+          process.exit(1);
+        }
+
+        const apiBaseUrl = resolveApiBaseUrl(options.apiBaseUrl);
+        const creds = await ensureLogin(apiBaseUrl);
+        if (!creds) {
+          console.error('Run `sungen login` first, then re-send your feedback.');
+          process.exit(1);
+        }
+
+        const payload: FeedbackPayload = {
+          content: text,
+          category: options.category,
+          sungen_version: SUNGEN_VERSION,
+          os: process.platform,
+          source: 'cli',
+        };
+
+        try {
+          const { id } = await submitFeedback(creds.api_base_url, creds.token, payload);
+          console.log(`Feedback submitted (id=${id}).`);
+        } catch (err) {
+          if (err instanceof AuthExpiredError) {
+            // Token died between load and POST — re-login once, then retry.
+            const yes = await promptYesNo('Your session expired. Log in again and retry? (y/n) ');
+            if (!yes) { console.error('Aborted.'); process.exit(1); }
+            const fresh = await performLogin(apiBaseUrl);
+            const { id } = await submitFeedback(fresh.api_base_url, fresh.token, payload);
+            console.log(`Feedback submitted (id=${id}).`);
+          } else {
+            throw err;
+          }
         }
-        console.log('');
       } catch (e) {
         console.error('Error:', e instanceof Error ? e.message : e);
         process.exit(1);

package/src/cli/commands/login.ts

@@ -0,0 +1,75 @@
+/**
+ * `sungen login` / `sungen logout`.
+ *
+ * login  — RFC 8252 native-app login (PKCE-S256 + loopback + one-time code)
+ *          against the FastSchema backend; caches the token at
+ *          ~/.sungen/credentials.json (0600).
+ * logout — clears that file.
+ *
+ * Mirrors the structure of `commands/figma.ts` (commander + scrubbed errors).
+ */
+
+import { Command } from 'commander';
+import { generatePkce, randomCorrelation } from '../../tools/sungen-auth/pkce';
+import { startLoopback } from '../../tools/sungen-auth/loopback-server';
+import { runLoginFlow } from '../../tools/sungen-auth/login-flow';
+import { saveCredentials, clearCredentials, credentialsPath } from '../../tools/sungen-auth/credentials-store';
+import { openBrowser } from '../../tools/sungen-auth/open-browser';
+import { resolveApiBaseUrl } from '../../tools/sungen-auth/api-base-url';
+import type { Credentials } from '../../tools/sungen-auth/sungen-auth-types';
+
+/**
+ * Run the full login flow against `apiBaseUrl`, persist the token, and return
+ * the stored credentials. Reused by `sungen feedback` for on-demand re-auth.
+ */
+export async function performLogin(apiBaseUrl: string): Promise<Credentials> {
+  const pkce = generatePkce();
+  const correlation = randomCorrelation();
+  const loopback = await startLoopback();
+  try {
+    const result = await runLoginFlow({
+      apiBaseUrl,
+      pkce,
+      correlation,
+      redirectUri: loopback.redirectUri,
+      openBrowser,
+      waitForCode: (corr, timeoutMs) => loopback.waitForCode(corr, timeoutMs),
+    });
+    const creds: Credentials = {
+      token: result.token,
+      email: result.email,
+      api_base_url: apiBaseUrl,
+      expires_at: result.expires_at,
+    };
+    saveCredentials(creds);
+    return creds;
+  } finally {
+    loopback.close();
+  }
+}
+
+export function registerLoginCommand(program: Command): void {
+  program
+    .command('login')
+    .description('Log in to the sungen feedback backend (opens your browser)')
+    .option('--api-base-url <url>', 'Backend base URL (overrides SUNGEN_API_BASE_URL + stored value)')
+    .action(async (options: { apiBaseUrl?: string }) => {
+      const apiBaseUrl = resolveApiBaseUrl(options.apiBaseUrl);
+      try {
+        const creds = await performLogin(apiBaseUrl);
+        console.log(`Logged in as ${creds.email}.`);
+        console.log(`Token saved to ${credentialsPath()} (mode 0600).`);
+      } catch (err: any) {
+        console.error(`Login failed: ${err?.message ?? err}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('logout')
+    .description('Remove the cached sungen login token')
+    .action(() => {
+      clearCredentials();
+      console.log(`Logged out. Removed ${credentialsPath()} (if present).`);
+    });
+}

package/src/cli/commands/qa-feedback.ts

@@ -0,0 +1,77 @@
+/**
+ * `sungen qa-feedback` — the LOCAL QA-feedback log (test-design knowledge +
+ * product telemetry), persisted to .sungen/feedback/feedback.jsonl.
+ *
+ * This is the persistence primitive behind the `/sungen:feedback` slash command
+ * (which auto-attaches screen/viewpoint/decision context and then calls
+ * `sungen qa-feedback record`). It is rarely typed by hand.
+ *
+ * NOTE: distinct from `sungen feedback` (see commands/feedback.ts) — that command
+ * submits PRODUCT feedback to the remote backend. This one only writes locally.
+ */
+
+import { Command } from 'commander';
+import { recordFeedback, summarize, FeedbackType, FeedbackDecision } from '../../harness/feedback';
+
+const TYPES = ['test-design', 'product', 'other'];
+const DECISIONS = ['accept', 'reject', 'edit', 'add', 'none'];
+
+export function registerQaFeedbackCommand(program: Command): void {
+  const fb = program
+    .command('qa-feedback')
+    .description('Local-first QA feedback log (test-design knowledge + product telemetry). Primarily invoked by the /sungen:feedback slash command.');
+
+  fb
+    .command('record')
+    .description('Record a feedback entry')
+    .requiredOption('--message <text>', 'The feedback')
+    .option('--type <t>', `Feedback type (${TYPES.join('|')})`, 'test-design')
+    .option('-s, --screen <name>', 'Screen/flow the feedback relates to')
+    .option('--target <ref>', 'What it is about (viewpoint id / scenario / command / artifact)')
+    .option('--decision <d>', `QA decision (${DECISIONS.join('|')})`, 'none')
+    .option('--reason <text>', 'Why')
+    .option('--source <who>', 'Who gave the feedback', 'qa')
+    .action((o) => {
+      try {
+        if (!TYPES.includes(o.type)) throw new Error(`--type must be one of ${TYPES.join(', ')}`);
+        if (!DECISIONS.includes(o.decision)) throw new Error(`--decision must be one of ${DECISIONS.join(', ')}`);
+        const p = recordFeedback({
+          type: o.type as FeedbackType,
+          screen: o.screen,
+          target: o.target,
+          decision: o.decision as FeedbackDecision,
+          message: o.message,
+          reason: o.reason,
+          source: o.source,
+        });
+        console.log(`✓ feedback recorded (${o.type}${o.screen ? ' · ' + o.screen : ''}) → ${p}`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  fb
+    .command('list')
+    .description('List / summarise recorded feedback')
+    .option('-s, --screen <name>', 'Filter by screen')
+    .option('--type <t>', 'Filter by type')
+    .option('--json', 'Output raw JSON')
+    .action((o) => {
+      try {
+        const s = summarize({ screen: o.screen, type: o.type });
+        if (o.json) { console.log(JSON.stringify(s, null, 2)); return; }
+        console.log(`\n━━━ Feedback (${s.total}) ━━━`);
+        console.log(`  by type: ${Object.entries(s.byType).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}`);
+        console.log(`  by decision: ${Object.entries(s.byDecision).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}\n`);
+        for (const e of s.entries.slice(-20)) {
+          console.log(`  [${e.type}${e.decision && e.decision !== 'none' ? '/' + e.decision : ''}] ${e.screen ? e.screen + ' · ' : ''}${e.target ? e.target + ' — ' : ''}${e.message}`);
+          if (e.reason) console.log(`      reason: ${e.reason}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
 import { registerLedgerCommand } from './commands/ledger';
 import { registerFeedbackCommand } from './commands/feedback';
+import { registerQaFeedbackCommand } from './commands/qa-feedback';
 import { registerScriptCheckCommand } from './commands/script-check';
 import { registerTraceCommand } from './commands/trace';
 import { registerChallengeCommand } from './commands/challenge';
@@ -31,6 +32,7 @@ import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
 import { registerContextCommand } from './commands/context';
 import { registerRepairCommand } from './commands/repair';
+import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 
@@ -66,6 +68,7 @@ async function main() {
   registerManifestCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);
+  registerQaFeedbackCommand(program);
   registerScriptCheckCommand(program);
   registerTraceCommand(program);
   registerChallengeCommand(program);
@@ -76,6 +79,7 @@ async function main() {
   registerRepairCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
+  registerLoginCommand(program);
 
   // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
   // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.