@sun-asterisk/sungen 3.2.3-beta.3 → 3.2.4

package/dist/orchestrator/templates/ai-src/commands/feedback.md

@@ -10,10 +10,10 @@ codex-trigger: "Run when the user wants to send FEEDBACK about sungen itself."
 ## Role
 {{#cap parallel-subagents}}
 
-You capture QA feedback and store it **locally** (no server) via `sungen feedback record`. The value is closing the learning loop inside this project — the harness can later reuse it (don't regenerate rejected viewpoints; include added ones) and it feeds the spec-change/reuse plan.
+You capture QA feedback and store it **locally** (no server) via `sungen qa-feedback record`. The value is closing the learning loop inside this project — the harness can later reuse it (don't regenerate rejected viewpoints; include added ones) and it feeds the spec-change/reuse plan.
 {{/cap}}
 {{^cap parallel-subagents}}
-Capture QA feedback and store it **locally** (no server) via `sungen feedback record`. Closes the learning loop inside the project; the harness can reuse it later.
+Capture QA feedback and store it **locally** (no server) via `sungen qa-feedback record`. Closes the learning loop inside the project; the harness can reuse it later.
 {{/cap}}
 
 ## Steps
@@ -39,12 +39,12 @@ Capture QA feedback and store it **locally** (no server) via `sungen feedback re
 {{/cap}}
    ```bash
 {{#cap parallel-subagents}}
-   sungen feedback record --type test-design --screen <name> \
+   sungen qa-feedback record --type test-design --screen <name> \
      --target "VP-DATA-CONSISTENCY" --decision add \
      --message "<message>" --reason "<why>"
 {{/cap}}
 {{^cap parallel-subagents}}
-   sungen feedback record --type <type> --screen <name> --target "<ref>" --decision <d> --message "<msg>" --reason "<why>"
+   sungen qa-feedback record --type <type> --screen <name> --target "<ref>" --decision <d> --message "<msg>" --reason "<why>"
 {{/cap}}
    ```
 {{#cap parallel-subagents}}
@@ -60,8 +60,8 @@ Capture QA feedback and store it **locally** (no server) via `sungen feedback re
 {{#cap parallel-subagents}}
 - **Never send anywhere** — this only writes a local file.
 - Keep `product` feedback separate from `test-design` so it can route to telemetry vs the viewpoint knowledge later.
-- View history: `sungen feedback list [--screen <name>] [--type <t>]`.
+- View history: `sungen qa-feedback list [--screen <name>] [--type <t>]`.
 {{/cap}}
 {{^cap parallel-subagents}}
-- Never send anywhere — local file only. Keep `product` vs `test-design` distinct. View: `sungen feedback list`.
+- Never send anywhere — local file only. Keep `product` vs `test-design` distinct. View: `sungen qa-feedback list`.
 {{/cap}}

package/dist/orchestrator/templates/ai-src/commands/locale.md

@@ -1,8 +1,8 @@
 ---
-description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright, generate test-data overlay so `sungen:run-test --env <locale>` works."
+description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright (web) or device locale (mobile), generate test-data overlay so `sungen:run-test --env <locale>` works."
 argument-hint: "<name> <locale> [--base-locale <code>] [--offline]"
 order: 45
-claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state"
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__generate_locators"
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*]"
 codex-trigger: "Run when the user asks to bootstrap i18n/localization for a screen. Runs before run-test --env <locale>."
 ---
@@ -33,6 +33,27 @@ Reject if name == locale (common typo).
 Reject if name == locale.
 {{/cap}}
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → switch to the **mobile path** (below).
+- If `platform: web` or field absent → follow the **web path** (existing behavior below, unchanged).
+
+### Mobile path
+
+When `platform: mobile`, mobile follows the **device locale** — there is no URL prefix, query param, or browser-storage mechanism to detect. Key differences from web (full detail in the `sungen-locale` skill):
+
+- **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` with the device at base locale → `appium_get_page_source` / `appium_screenshot`) — not Playwright browser tools.
+- **Locale-switch mechanism**: `appium:language` / `appium:locale` capabilities + `noReset:false`, resolved automatically at runtime by `wdio.conf.ts`'s `resolveLocaleCaps()`. No fixture files needed.
+- **Phases skipped**: 3.5/3.6 (browser storage diff/verify) and 6d/6f (Pages URL update, locale-config.json) are web-only — skip them. Phase 6 (mobile) writes only selectors `{{var}}`, the base `test-data/<feature>.yaml`, and the overlay `test-data/<feature>.<locale>.yaml`.
+- **Compile**: `sungen generate --screen <name>` (the Appium adapter auto-selects for a mobile project).
+- **Hand-off**: after a locale run, print `SUNGEN_ENV=<locale> npm run test:mobile` (or the `--flow` equivalent). If the device's locale code differs from the overlay's env name, set `SUNGEN_LOCALE=<code>` — `resolveLocaleCaps()` reads it as an override.
+- **Reset after a locale run**: run once with `SUNGEN_LOCALE=en npm run test:mobile` to bring the device/app back to the base language before the next non-locale run.
+- **iOS data-wipe**: `wdio.conf.ts`'s `beforeSession` hook already wipes the app's data container on iOS before any locale run (XCUITest's `noReset:false` alone doesn't clear a persisted in-app language). If an older mobile project's `wdio.conf.ts` predates this hook and iOS keeps the previous language, re-run `sungen init --mobile` to refresh it.
+
+Stop here for mobile — do not continue to the web path below. Everything else (the 7-phase strategy, selector/test-data output shape, `{{var}}` overlay pattern) matches web; see the `sungen-locale` skill for the full mobile phase table.
+
 ## Auto-detect context
 
 Same as `/sungen:run-test`:
@@ -114,10 +135,11 @@ Offer the user:
 {{#cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor. This command only PREPS files.
 - Do NOT modify `.feature` files. Localization happens entirely through `selectors/*.yaml` + `test-data/*.yaml`.
-- Auth blocker on SAA staging? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Auth blocker on SAA staging (web)? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Mobile device/emulator unreachable? Use `--offline` — same fallback as web.
 {{/cap}}
 {{^cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor; this command only PREPS files.
 - Do NOT modify `.feature` files. Localization lives in `selectors/*.yaml` + `test-data/*.yaml` only.
-- Auth blocked? Use `--offline`.
+- Auth blocked (web)? Use `--offline`. Mobile device unreachable? Same fallback.
 {{/cap}}

package/dist/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -78,19 +78,20 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 
 ---
 
-## XLSX sheets — Auto / Manual split
+## XLSX sheets — Overview + Auto / Manual split
 
-The `.xlsx` is split into two sheets so QA manages the sets separately:
+The `.xlsx` leads with an **`Overview`** roll-up sheet, then splits the test cases into detail sheets so QA manages the sets separately:
+- **`Overview`** — first sheet. Same masthead (Sun\* logo, `<SCREEN> TESTCASE` title, No/Version/Issue-Date, ISO band) as the others, then a summary table: one row per following sheet with `# · Sheet name · Passed · Failed · Pending · N/A · Remain · Total`, plus a grand-total row. `Remain = Total − Passed − N/A` (i.e. Failed + Pending), reconciling with each detail sheet's own summary band.
 - **`Auto`** — automatable test cases (`Auto` + `Not compiled`).
 - **`Manual`** — `@manual` test cases (always present, header-only when there are none).
 
-Multi-locale (no `SUNGEN_ENV`): one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual.
+Multi-locale (no `SUNGEN_ENV`): `Overview` + one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual. The Overview lists every detail sheet, so each locale's counts appear on its own row.
 
 ---
 
 ## API delivery — extra worksheet
 
-For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a third worksheet **`API detail`** (appended after Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
+For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a final worksheet **`API detail`** (appended after Overview/Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
 
 ### Required sources (API detail sheet only)
 

package/dist/orchestrator/templates/wdio.conf.ts

@@ -25,6 +25,7 @@ import dotenv from 'dotenv';
 dotenv.config({ path: '.env.appium' });
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { execSync } from 'node:child_process';
 import PwShapeReporter from './specs/reporters/pw-shape-reporter';
 
 /**
@@ -104,13 +105,34 @@ const RUN_ANDROID = MOBILE_PLATFORM === 'android' || MOBILE_PLATFORM === 'both';
 const RUN_IOS = MOBILE_PLATFORM === 'ios' || MOBILE_PLATFORM === 'both';
 const IOS_APP = process.env.IOS_APP;
 const IOS_BUNDLE_ID = process.env.IOS_BUNDLE_ID || '__IOS_BUNDLE_ID__';
-const IOS_DEVICE = process.env.IOS_DEVICE || '__IOS_DEVICE__';
-const IOS_VERSION = process.env.IOS_VERSION || '__IOS_VERSION__';
+const IOS_UDID = process.env.IOS_UDID;
+// When a specific Simulator is targeted by IOS_UDID, XCUITest uses THAT device and IGNORES the
+// deviceName/platformVersion caps — so a stale IOS_DEVICE/IOS_VERSION would MISLABEL the deliverable's
+// "Test Environment". Resolve the real device name + iOS runtime from the UDID via simctl so the caps
+// (and the reporter's label) reflect reality. Explicit IOS_DEVICE/IOS_VERSION still win; on a real
+// device / non-mac, simctl fails → fall back to the provided/scaffold values.
+function resolveSimDevice(udid: string): { name?: string; version?: string } {
+  try {
+    const data = JSON.parse(execSync('xcrun simctl list devices --json', { encoding: 'utf-8' })) as {
+      devices?: Record<string, Array<{ udid: string; name: string }>>;
+    };
+    for (const [runtime, devs] of Object.entries(data.devices || {})) {
+      const hit = devs.find((d) => d.udid === udid);
+      if (hit) {
+        const vm = /iOS-(\d+)-(\d+)/.exec(runtime); // com.apple.CoreSimulator.SimRuntime.iOS-26-3
+        return { name: hit.name, version: vm ? `${vm[1]}.${vm[2]}` : undefined };
+      }
+    }
+  } catch { /* simctl unavailable (real device / non-mac) → keep provided values */ }
+  return {};
+}
+const IOS_SIM = IOS_UDID ? resolveSimDevice(IOS_UDID) : {};
+const IOS_DEVICE = process.env.IOS_DEVICE || IOS_SIM.name || '__IOS_DEVICE__';
+const IOS_VERSION = process.env.IOS_VERSION || IOS_SIM.version || '__IOS_VERSION__';
 // platformVersion is OPTIONAL on a real device: with IOS_UDID set, XCUITest reads the iOS version off
 // the connected device. Only pass the cap when IOS_VERSION is a real value (not the unfilled scaffold
 // placeholder). On a Simulator set it (or IOS_DEVICE) so Appium picks a matching runtime.
 const HAS_REAL_IOS_VERSION = !!IOS_VERSION && IOS_VERSION !== '__IOS_VERSION__';
-const IOS_UDID = process.env.IOS_UDID;
 // Real iPhone (device) — WebDriverAgent must be code-signed onto it. Set IOS_TEAM_ID (your Apple
 // Team ID) to switch the iOS cap into real-device mode; the Simulator ignores these (they're only
 // emitted when IOS_TEAM_ID is present, so Simulator runs are unchanged). For a real device also set
@@ -208,6 +230,13 @@ export const config: WebdriverIO.Config = {
           {
             platformName: 'iOS',
             'appium:automationName': 'XCUITest',
+            // Flutter apps NEVER report "idle" to XCUITest, so WDA always waits the FULL
+            // waitForIdleTimeout before EVERY interaction. The default (~10s) makes gesture
+            // loops blow the mocha timeout; 0 removes the wait entirely but then taps fire
+            // mid-transition/mid-launch and randomly miss (measured: ~2 flaky scenarios per
+            // run). 2s is the working balance — a universal settle that covers Flutter
+            // transitions while keeping bounded scroll/error paths well inside the budget.
+            'appium:waitForIdleTimeout': 2,
             'appium:deviceName': IOS_DEVICE,
             // Omit when unknown (real device, no IOS_VERSION) → XCUITest reads it from the device by udid.
             ...(HAS_REAL_IOS_VERSION ? { 'appium:platformVersion': IOS_VERSION } : {}),
@@ -253,6 +282,13 @@ export const config: WebdriverIO.Config = {
   mochaOpts: {
     ui: 'bdd',
     timeout: 120000,
+    // One retry per test: the relaunch-per-scenario pattern on a Flutter sim has a residual
+    // launch race (~10%/scenario — the first interaction can fire before the app routes
+    // touches), with a RANDOM victim each run. A retry re-runs the full beforeEach (fresh
+    // relaunch), so race victims recover on attempt 2 while real failures (wrong expected
+    // value, missing element) fail both attempts and still report Failed. The reporter and
+    // delivery already take the LAST attempt.
+    retries: 1,
   },
 
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container

package/dist/tools/sungen-api/edit-in-editor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Open the user's editor to compose feedback text, à la `git commit`.
+ *
+ * The feedback body is MARKDOWN, so the editor buffer is left completely
+ * untouched — no comment/instruction lines are injected or stripped (that would
+ * clobber markdown `#` headings). Guidance is printed to the terminal before the
+ * editor launches instead. Returns the trimmed body, or null when it is empty
+ * (caller treats that as "abort").
+ */
+/**
+ * Open the editor and return the composed feedback (verbatim, trimmed), or null
+ * if empty/aborted. Throws if the editor cannot be launched or exits non-zero.
+ */
+export declare function composeInEditor(): string | null;
+//# sourceMappingURL=edit-in-editor.d.ts.map

package/dist/tools/sungen-api/edit-in-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-in-editor.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-api/edit-in-editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAmB/C"}

package/dist/tools/sungen-api/edit-in-editor.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Open the user's editor to compose feedback text, à la `git commit`.
+ *
+ * The feedback body is MARKDOWN, so the editor buffer is left completely
+ * untouched — no comment/instruction lines are injected or stripped (that would
+ * clobber markdown `#` headings). Guidance is printed to the terminal before the
+ * editor launches instead. Returns the trimmed body, or null when it is empty
+ * (caller treats that as "abort").
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeInEditor = composeInEditor;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Resolve the editor command, mirroring git's precedence. */
+function resolveEditor() {
+    return (process.env.VISUAL ||
+        process.env.EDITOR ||
+        (process.platform === 'win32' ? 'notepad' : 'vi'));
+}
+/**
+ * Open the editor and return the composed feedback (verbatim, trimmed), or null
+ * if empty/aborted. Throws if the editor cannot be launched or exits non-zero.
+ */
+function composeInEditor() {
+    const file = path.join(os.tmpdir(), `sungen-feedback-${process.pid}-${Date.now()}.md`);
+    fs.writeFileSync(file, '', 'utf8');
+    try {
+        const editor = resolveEditor();
+        console.error('Composing feedback in your editor (markdown supported). Save & close to submit; leave empty to abort.');
+        // shell:true so editors with args work (e.g. VISUAL="code --wait").
+        const result = (0, child_process_1.spawnSync)(`${editor} "${file}"`, { shell: true, stdio: 'inherit' });
+        if (result.error)
+            throw new Error(`Could not launch editor "${editor}": ${result.error.message}`);
+        if (typeof result.status === 'number' && result.status !== 0) {
+            throw new Error(`Editor "${editor}" exited with code ${result.status}.`);
+        }
+        // Verbatim — only trim outer whitespace so markdown (headings, lists, code
+        // fences, HTML comments) is preserved exactly as written.
+        const body = fs.readFileSync(file, 'utf8').trim();
+        return body.length > 0 ? body : null;
+    }
+    finally {
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* best effort */ }
+    }
+}
+//# sourceMappingURL=edit-in-editor.js.map

package/dist/tools/sungen-api/edit-in-editor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-in-editor.js","sourceRoot":"","sources":["../../../src/tools/sungen-api/edit-in-editor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBH,0CAmBC;AArCD,iDAA0C;AAC1C,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAE7B,8DAA8D;AAC9D,SAAS,aAAa;IACpB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,MAAM;QAClB,OAAO,CAAC,GAAG,CAAC,MAAM;QAClB,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAClD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,mBAAmB,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvF,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,uGAAuG,CAAC,CAAC;QACvH,oEAAoE;QACpE,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,GAAG,MAAM,KAAK,IAAI,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,IAAI,MAAM,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAClG,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,sBAAsB,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3E,CAAC;QACD,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC"}

package/dist/tools/sungen-api/feedback-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thin client for submitting product feedback to the FastSchema backend.
+ * Raw fetch (the fastschema npm SDK is browser/cookie-oriented and has no
+ * bearer-token content client). author is NEVER sent — the server stamps it.
+ */
+/** Thrown on 401 so the caller can prompt a re-login and retry once. */
+export declare class AuthExpiredError extends Error {
+    constructor(message?: string);
+}
+export interface FeedbackPayload {
+    content: string;
+    category: string;
+    sungen_version?: string;
+    os?: string;
+    source: string;
+}
+/**
+ * POST one feedback record. Returns the created row id.
+ * @throws AuthExpiredError on 401; Error (scrubbed) on any other non-2xx.
+ */
+export declare function submitFeedback(apiBaseUrl: string, token: string, payload: FeedbackPayload): Promise<{
+    id: number | string;
+}>;
+//# sourceMappingURL=feedback-client.d.ts.map

package/dist/tools/sungen-api/feedback-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-client.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-api/feedback-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wEAAwE;AACxE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAA4B;CAIhD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC,CA2BlC"}

package/dist/tools/sungen-api/feedback-client.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Thin client for submitting product feedback to the FastSchema backend.
+ * Raw fetch (the fastschema npm SDK is browser/cookie-oriented and has no
+ * bearer-token content client). author is NEVER sent — the server stamps it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthExpiredError = void 0;
+exports.submitFeedback = submitFeedback;
+/** Thrown on 401 so the caller can prompt a re-login and retry once. */
+class AuthExpiredError extends Error {
+    constructor(message = 'Authentication expired.') {
+        super(message);
+        this.name = 'AuthExpiredError';
+    }
+}
+exports.AuthExpiredError = AuthExpiredError;
+function normalizeBase(url) {
+    return url.replace(/\/+$/, '');
+}
+/**
+ * POST one feedback record. Returns the created row id.
+ * @throws AuthExpiredError on 401; Error (scrubbed) on any other non-2xx.
+ */
+async function submitFeedback(apiBaseUrl, token, payload) {
+    let res;
+    try {
+        res = await fetch(`${normalizeBase(apiBaseUrl)}/api/content/feedback`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        throw new Error(`Network error reaching the feedback backend: ${err?.message ?? 'unknown'}`);
+    }
+    if (res.status === 401)
+        throw new AuthExpiredError();
+    if (!res.ok) {
+        // Scrub the body — never echo a raw server error that might carry internals.
+        throw new Error(`Feedback submission failed (HTTP ${res.status}).`);
+    }
+    const body = (await res.json().catch(() => ({})));
+    // FastSchema content create returns the row (id at top level or under .data).
+    // Only accept an actual id value — never fall back to the whole object (would
+    // print "[object Object]").
+    const id = body?.id ?? body?.data?.id ?? 'unknown';
+    return { id };
+}
+//# sourceMappingURL=feedback-client.js.map

package/dist/tools/sungen-api/feedback-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-client.js","sourceRoot":"","sources":["../../../src/tools/sungen-api/feedback-client.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AA0BH,wCA+BC;AAvDD,wEAAwE;AACxE,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AALD,4CAKC;AAUD,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,KAAa,EACb,OAAwB;IAExB,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,uBAAuB,EAAE;YACrE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,EAAE;aACjC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,EAAE,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,gBAAgB,EAAE,CAAC;IACrD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAQ,CAAC;IACzD,8EAA8E;IAC9E,8EAA8E;IAC9E,4BAA4B;IAC5B,MAAM,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI,SAAS,CAAC;IACnD,OAAO,EAAE,EAAE,EAAE,CAAC;AAChB,CAAC"}

package/dist/tools/sungen-api/read-stdin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read piped stdin to a string. Returns null when stdin is a TTY (interactive),
+ * so callers can distinguish "no piped input" from "empty pipe".
+ */
+export declare function readStdin(): Promise<string | null>;
+//# sourceMappingURL=read-stdin.d.ts.map

package/dist/tools/sungen-api/read-stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-stdin.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-api/read-stdin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASlD"}

package/dist/tools/sungen-api/read-stdin.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Read piped stdin to a string. Returns null when stdin is a TTY (interactive),
+ * so callers can distinguish "no piped input" from "empty pipe".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStdin = readStdin;
+function readStdin() {
+    if (process.stdin.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+//# sourceMappingURL=read-stdin.js.map

package/dist/tools/sungen-api/read-stdin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-stdin.js","sourceRoot":"","sources":["../../../src/tools/sungen-api/read-stdin.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAEH,8BASC;AATD,SAAgB,SAAS;IACvB,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/sungen-auth/api-base-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolves the feedback backend base URL with a fixed precedence so `login` and
+ * `feedback` agree on where to talk.
+ *
+ * Precedence: explicit flag > SUNGEN_API_BASE_URL env > stored credential's
+ * api_base_url > DEFAULT_API_BASE_URL.
+ *
+ * DEFAULT_API_BASE_URL is the deployed production host, so the common case needs
+ * no config; override via --api-base-url / SUNGEN_API_BASE_URL for dev/staging.
+ */
+/** Deployed feedback backend (production). Override with SUNGEN_API_BASE_URL locally. */
+export declare const DEFAULT_API_BASE_URL = "https://sungen.sun-asterisk.vn";
+export declare function resolveApiBaseUrl(flagValue?: string): string;
+//# sourceMappingURL=api-base-url.d.ts.map

package/dist/tools/sungen-auth/api-base-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-base-url.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-auth/api-base-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,mCAAmC,CAAC;AAErE,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D"}

package/dist/tools/sungen-auth/api-base-url.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Resolves the feedback backend base URL with a fixed precedence so `login` and
+ * `feedback` agree on where to talk.
+ *
+ * Precedence: explicit flag > SUNGEN_API_BASE_URL env > stored credential's
+ * api_base_url > DEFAULT_API_BASE_URL.
+ *
+ * DEFAULT_API_BASE_URL is the deployed production host, so the common case needs
+ * no config; override via --api-base-url / SUNGEN_API_BASE_URL for dev/staging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_BASE_URL = void 0;
+exports.resolveApiBaseUrl = resolveApiBaseUrl;
+const credentials_store_1 = require("./credentials-store");
+/** Deployed feedback backend (production). Override with SUNGEN_API_BASE_URL locally. */
+exports.DEFAULT_API_BASE_URL = 'https://sungen.sun-asterisk.vn';
+function resolveApiBaseUrl(flagValue) {
+    if (flagValue)
+        return flagValue;
+    if (process.env.SUNGEN_API_BASE_URL)
+        return process.env.SUNGEN_API_BASE_URL;
+    const stored = (0, credentials_store_1.loadCredentials)();
+    if (stored?.api_base_url)
+        return stored.api_base_url;
+    return exports.DEFAULT_API_BASE_URL;
+}
+//# sourceMappingURL=api-base-url.js.map

package/dist/tools/sungen-auth/api-base-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-base-url.js","sourceRoot":"","sources":["../../../src/tools/sungen-auth/api-base-url.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAOH,8CAMC;AAXD,2DAAsD;AAEtD,yFAAyF;AAC5E,QAAA,oBAAoB,GAAG,gCAAgC,CAAC;AAErE,SAAgB,iBAAiB,CAAC,SAAkB;IAClD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAC5E,MAAM,MAAM,GAAG,IAAA,mCAAe,GAAE,CAAC;IACjC,IAAI,MAAM,EAAE,YAAY;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IACrD,OAAO,4BAAoB,CAAC;AAC9B,CAAC"}

package/dist/tools/sungen-auth/credentials-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * User-level credential storage at ~/.sungen/credentials.json.
+ *
+ * Deliberately user-scoped (not project-local like the Figma PAT in .env): the
+ * login token is tied to the person and works across every sungen project.
+ * File mode 0600, parent dir 0700 — the token is a bearer secret.
+ */
+import type { Credentials } from './sungen-auth-types';
+/** Absolute path to the credentials file (~/.sungen/credentials.json). */
+export declare function credentialsPath(): string;
+/** Load stored credentials, or null when absent / unreadable / malformed. */
+export declare function loadCredentials(): Credentials | null;
+/** Persist credentials with restrictive permissions (dir 0700, file 0600). */
+export declare function saveCredentials(creds: Credentials): void;
+/** Remove the credentials file; no-op when absent. */
+export declare function clearCredentials(): void;
+/** True when the credential carries an expiry that is already past (no refresh token — prompt re-login on expiry). */
+export declare function isExpired(creds: Credentials): boolean;
+//# sourceMappingURL=credentials-store.d.ts.map

package/dist/tools/sungen-auth/credentials-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-store.d.ts","sourceRoot":"","sources":["../../../src/tools/sungen-auth/credentials-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD,0EAA0E;AAC1E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,WAAW,GAAG,IAAI,CASpD;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAOxD;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAED,sHAAsH;AACtH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAGrD"}

package/dist/tools/sungen-auth/credentials-store.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * User-level credential storage at ~/.sungen/credentials.json.
+ *
+ * Deliberately user-scoped (not project-local like the Figma PAT in .env): the
+ * login token is tied to the person and works across every sungen project.
+ * File mode 0600, parent dir 0700 — the token is a bearer secret.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentialsPath = credentialsPath;
+exports.loadCredentials = loadCredentials;
+exports.saveCredentials = saveCredentials;
+exports.clearCredentials = clearCredentials;
+exports.isExpired = isExpired;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const DIR_NAME = '.sungen';
+const FILE_NAME = 'credentials.json';
+/** Absolute path to the credentials file (~/.sungen/credentials.json). */
+function credentialsPath() {
+    return path.join(os.homedir(), DIR_NAME, FILE_NAME);
+}
+/** Load stored credentials, or null when absent / unreadable / malformed. */
+function loadCredentials() {
+    try {
+        const raw = fs.readFileSync(credentialsPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.token !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist credentials with restrictive permissions (dir 0700, file 0600). */
+function saveCredentials(creds) {
+    const dir = path.join(os.homedir(), DIR_NAME);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const fp = credentialsPath();
+    // Write then chmod so an existing looser-mode file is tightened too.
+    fs.writeFileSync(fp, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    fs.chmodSync(fp, 0o600);
+}
+/** Remove the credentials file; no-op when absent. */
+function clearCredentials() {
+    try {
+        fs.unlinkSync(credentialsPath());
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** True when the credential carries an expiry that is already past (no refresh token — prompt re-login on expiry). */
+function isExpired(creds) {
+    if (typeof creds.expires_at !== 'number')
+        return false;
+    return creds.expires_at * 1000 <= Date.now();
+}
+//# sourceMappingURL=credentials-store.js.map

package/dist/tools/sungen-auth/credentials-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-store.js","sourceRoot":"","sources":["../../../src/tools/sungen-auth/credentials-store.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWH,0CAEC;AAGD,0CASC;AAGD,0CAOC;AAGD,4CAMC;AAGD,8BAGC;AAhDD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAG7B,MAAM,QAAQ,GAAG,SAAS,CAAC;AAC3B,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,0EAA0E;AAC1E,SAAgB,eAAe;IAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AACtD,CAAC;AAED,6EAA6E;AAC7E,SAAgB,eAAe;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC;QAC9C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7D,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,SAAgB,eAAe,CAAC,KAAkB;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC9C,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,eAAe,EAAE,CAAC;IAC7B,qEAAqE;IACrE,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,sDAAsD;AACtD,SAAgB,gBAAgB;IAC9B,IAAI,CAAC;QACH,EAAE,CAAC,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;AACH,CAAC;AAED,sHAAsH;AACtH,SAAgB,SAAS,CAAC,KAAkB;IAC1C,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,KAAK,CAAC,UAAU,GAAG,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AAC/C,CAAC"}