@nac3/forge-cli 0.2.0-alpha.1

package/dist/voice/voiceprint/trust.js

@@ -0,0 +1,150 @@
+/**
+ * Trust state machine for the voice subsystem.
+ *
+ * Five layers, concentric. Outer layers ALWAYS apply -- a user
+ * who switches off the voiceprint check (Layer 2) still has
+ * the audit log (Layer 4) and the optional institutional
+ * remote review (Layer 5) on top.
+ *
+ *   Layer 5: institutional log auditable from another device
+ *   Layer 4: rollback command + audit log
+ *   Layer 3: liveness check before irreversible ops
+ *   Layer 2: explicit voice toggle ("modo confianza on/off")
+ *   Layer 1: voiceprint match -> trust mode ON by default
+ *
+ * Operations are classified as:
+ *
+ *   - safe:        read-only. Never gated. Examples:
+ *                  forge.read_manifest, list_files,
+ *                  consult_nac_spec, reader operations.
+ *   - standard:    writes a file, runs tests, captures flow.
+ *                  Gated by Layer 1 (voiceprint match
+ *                  auto-approves; mismatch -> explicit
+ *                  confirmation unless permissive=true).
+ *   - irreversible: npm publish, git push --force, delete
+ *                  branch, delete file. Gated by Layer 3
+ *                  (liveness check regardless of trust state).
+ *
+ * The state machine is per-session: the explicit toggle
+ * applies until the chat / mic session ends. Persisting the
+ * toggle across sessions is intentionally OFF -- a fresh
+ * boot starts with Layer 1 active (voiceprint required).
+ *
+ * Loud failures: anything that would gate an op surfaces a
+ * voice-readable reason the panel renders.
+ *
+ * ASCII-only.
+ */
+import { DEFAULT_VOICEPRINT_CONFIG } from './types.js';
+export function freshTrustState() {
+    return {
+        override: null,
+        lastMatch: null,
+        activeIdentity: null,
+    };
+}
+/**
+ * Decide whether an operation may proceed given the current
+ * trust state + voice config.
+ *
+ * The caller is the chat tool dispatcher (server-side). On
+ * `requires_liveness: true` the dispatcher does NOT execute
+ * the tool immediately -- it kicks off a liveness challenge
+ * UI, waits for the result, then re-invokes decideTrust with
+ * the fresh identify outcome.
+ */
+export function decideTrust(operationClass, state, config = DEFAULT_VOICEPRINT_CONFIG) {
+    /* Safe ops are never gated. They land regardless of trust
+       state for a usable read-only experience. */
+    if (operationClass === 'safe') {
+        return {
+            allowed: true,
+            requires_liveness: false,
+            reason: 'safe operation -- read-only, no gating',
+            layer: 1,
+        };
+    }
+    /* Irreversible ops ALWAYS require liveness, regardless of
+       trust state. Layer 3 is non-overridable. */
+    if (operationClass === 'irreversible') {
+        return {
+            allowed: false,
+            requires_liveness: true,
+            reason: 'irreversible operation -- liveness check required',
+            layer: 3,
+        };
+    }
+    /* Standard ops: Layer 2 override wins, then Layer 1. */
+    if (state.override === 'off') {
+        return {
+            allowed: false,
+            requires_liveness: false,
+            reason: 'trust mode off -- explicit user confirmation required',
+            layer: 2,
+        };
+    }
+    if (state.override === 'on') {
+        return {
+            allowed: true,
+            requires_liveness: false,
+            reason: 'trust mode forced on by user',
+            layer: 2,
+        };
+    }
+    /* Layer 1: voiceprint match. */
+    if (state.lastMatch === null) {
+        /* No identify() ran yet -- err on the side of explicit
+           confirmation. */
+        return {
+            allowed: false,
+            requires_liveness: false,
+            reason: 'no voiceprint match yet -- speak once to identify yourself',
+            layer: 1,
+        };
+    }
+    if (state.lastMatch.matched === null) {
+        /* Speaker not recognised. */
+        if (config.permissive) {
+            return {
+                allowed: true,
+                requires_liveness: false,
+                reason: 'permissive mode -- unknown speaker allowed',
+                layer: 1,
+            };
+        }
+        return {
+            allowed: false,
+            requires_liveness: false,
+            reason: 'unknown speaker -- enroll first or toggle trust mode',
+            layer: 1,
+        };
+    }
+    /* Match found -- proceed. */
+    return {
+        allowed: true,
+        requires_liveness: false,
+        reason: 'voiceprint match: ' + state.lastMatch.matched
+            + ' (score ' + state.lastMatch.score.toFixed(2) + ')',
+        layer: 1,
+    };
+}
+/**
+ * Apply a fresh identify() outcome to the trust state. Mutates
+ * the state in place + returns it for chaining. When the match
+ * lands and there is no active identity yet, the matched name
+ * becomes the active identity for the session.
+ */
+export function ingestIdentify(state, match) {
+    state.lastMatch = match;
+    if (state.activeIdentity === null && match.matched) {
+        state.activeIdentity = match.matched;
+    }
+    return state;
+}
+/** Explicit user toggle (Layer 2). null clears the override
+ *  and falls back to Layer 1. */
+export function setOverride(state, override) {
+    state.override = override;
+    return state;
+}
+//# sourceMappingURL=trust.js.map

package/dist/voice/voiceprint/trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.js","sourceRoot":"","sources":["../../../src/voice/voiceprint/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAiCvD,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,cAA8B,EAC9B,KAAiB,EACjB,SAA2B,yBAAyB;IAEpD;kDAC8C;IAC9C,IAAI,cAAc,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,iBAAiB,EAAE,KAAK;YACxB,MAAM,EAAE,wCAAwC;YAChD,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IAED;kDAC8C;IAC9C,IAAI,cAAc,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,iBAAiB,EAAE,IAAI;YACvB,MAAM,EAAE,mDAAmD;YAC3D,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IAED,wDAAwD;IACxD,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,iBAAiB,EAAE,KAAK;YACxB,MAAM,EAAE,uDAAuD;YAC/D,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,iBAAiB,EAAE,KAAK;YACxB,MAAM,EAAE,8BAA8B;YACtC,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC7B;2BACmB;QACnB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,iBAAiB,EAAE,KAAK;YACxB,MAAM,EAAE,4DAA4D;YACpE,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACrC,6BAA6B;QAC7B,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,iBAAiB,EAAE,KAAK;gBACxB,MAAM,EAAE,4CAA4C;gBACpD,KAAK,EAAE,CAAC;aACT,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE,KAAK;YACd,iBAAiB,EAAE,KAAK;YACxB,MAAM,EAAE,sDAAsD;YAC9D,KAAK,EAAE,CAAC;SACT,CAAC;IACJ,CAAC;IACD,6BAA6B;IAC7B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,iBAAiB,EAAE,KAAK;QACxB,MAAM,EAAE,oBAAoB,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO;cAClD,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG;QACvD,KAAK,EAAE,CAAC;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB,EAAE,KAAkB;IAClE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC;IACxB,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnD,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;iCACiC;AACjC,MAAM,UAAU,WAAW,CAAC,KAAiB,EAAE,QAA6B;IAC1E,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/voice/voiceprint/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Voiceprint subsystem -- type surface.
+ *
+ * The voiceprint subsystem identifies who is speaking by
+ * computing a fixed-size embedding from an audio sample and
+ * comparing it against enrolled embeddings via cosine similarity.
+ *
+ * Provider pattern mirrors STT/TTS: an interface + multiple
+ * implementations registered with an ID. Default (alpha) is
+ * `local-mfcc-stub` -- a pure-Node placeholder good enough to
+ * exercise the state machine + types but NOT production
+ * quality. SpeechBrain via Python sidecar lands later;
+ * Google Speaker Recognition cloud is the configurable
+ * primary per Pablo's G-VOICE-1 decision (2026-05-23).
+ *
+ * ASCII-only.
+ */
+/** Identifiers for voiceprint providers. Open string union --
+ *  same pattern as the STT/TTS provider ids. */
+export type VoiceprintProviderId = 'local-mfcc-stub' | 'speechbrain-py' | 'google' | string;
+/** A computed embedding. Vectors are typically 256-dimensional
+ *  but the size is provider-specific; we store the length
+ *  alongside for sanity checks. */
+export interface VoiceprintEmbedding {
+    /** Embedding vector. Floats, typically L2-normalised by the
+     *  provider so cosine == dot product. */
+    vector: number[];
+    /** Length of vector. Stored explicitly so a deserialised
+     *  embedding can be validated cheaply. */
+    length: number;
+    /** Provider id that produced the embedding. Required so
+     *  matches across providers can be flagged loudly. */
+    source: VoiceprintProviderId;
+    /** ISO 8601 timestamp of enrollment. Audit trail. */
+    enrolled_at: string;
+}
+/** A request to extract an embedding from audio bytes. */
+export interface VoiceprintExtractRequest {
+    audio: Buffer;
+    /** Audio format. Same enum as the STT request. */
+    format: 'webm' | 'ogg' | 'wav' | 'mp3' | 'flac' | 'mp4';
+}
+/** Provider interface every voiceprint backend implements. */
+export interface VoiceprintProvider {
+    readonly id: VoiceprintProviderId;
+    /** Embedding dimensionality this provider produces.
+     *  Mismatches across providers fail the match step
+     *  loudly. */
+    readonly embeddingSize: number;
+    /** True when the provider has everything it needs.
+     *  Local stub is always ready; cloud providers check the
+     *  vault for credentials. */
+    readyToRun(): Promise<boolean>;
+    /** Extract an embedding from the audio. */
+    extract(req: VoiceprintExtractRequest): Promise<VoiceprintEmbedding>;
+}
+/** User-facing voiceprint configuration. Persisted in the same
+ *  ~/.yujin-forge/voice-config.json under the `voiceprint` key
+ *  added in this slice. */
+export interface VoiceprintConfig {
+    /** Active provider. */
+    provider: VoiceprintProviderId;
+    /** Cosine similarity threshold above which a match counts as
+     *  the enrolled speaker. Default 0.75 (conservative). */
+    threshold: number;
+    /** When true, mismatches do NOT block tool dispatch -- they
+     *  only annotate the audit log. Useful in development. */
+    permissive: boolean;
+}
+export declare const DEFAULT_VOICEPRINT_CONFIG: VoiceprintConfig;
+/** A single enrolled identity. Multiple identities can be
+ *  enrolled per install (parent + child + helper sharing a
+ *  workstation). */
+export interface EnrolledIdentity {
+    /** Stable identifier (snake_case). Used as a key in the
+     *  enrollment store. */
+    name: string;
+    /** The embedding extracted during enrollment. */
+    embedding: VoiceprintEmbedding;
+    /** Human-readable label shown to the user
+     *  ("Pablo", "Mama", "Helper"). */
+    label: string;
+    /** Free-form notes for the audit trail. */
+    notes?: string;
+}
+/** Result of a match against the enrolled set. */
+export interface MatchResult {
+    /** Name of the best-matching enrolled identity, or null when
+     *  no enrolled embedding exceeded the threshold. */
+    matched: string | null;
+    /** Cosine similarity score of the best match. */
+    score: number;
+    /** All scores for transparency / debugging. Map of name ->
+     *  score, sorted descending. */
+    ranked: Array<{
+        name: string;
+        score: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/voice/voiceprint/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/voice/voiceprint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;gDACgD;AAChD,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,gBAAgB,GAChB,QAAQ,GACR,MAAM,CAAC;AAEX;;mCAEmC;AACnC,MAAM,WAAW,mBAAmB;IAClC;6CACyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;8CAC0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf;0DACsD;IACtD,MAAM,EAAE,oBAAoB,CAAC;IAC7B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0DAA0D;AAC1D,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;CACzD;AAED,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC;;kBAEc;IACd,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;iCAE6B;IAC7B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,2CAA2C;IAC3C,OAAO,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtE;AAED;;2BAE2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;6DACyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;8DAC0D;IAC1D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF;;oBAEoB;AACpB,MAAM,WAAW,gBAAgB;IAC/B;4BACwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,SAAS,EAAE,mBAAmB,CAAC;IAC/B;uCACmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B;wDACoD;IACpD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd;oCACgC;IAChC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD"}

package/dist/voice/voiceprint/types.js

@@ -0,0 +1,23 @@
+/**
+ * Voiceprint subsystem -- type surface.
+ *
+ * The voiceprint subsystem identifies who is speaking by
+ * computing a fixed-size embedding from an audio sample and
+ * comparing it against enrolled embeddings via cosine similarity.
+ *
+ * Provider pattern mirrors STT/TTS: an interface + multiple
+ * implementations registered with an ID. Default (alpha) is
+ * `local-mfcc-stub` -- a pure-Node placeholder good enough to
+ * exercise the state machine + types but NOT production
+ * quality. SpeechBrain via Python sidecar lands later;
+ * Google Speaker Recognition cloud is the configurable
+ * primary per Pablo's G-VOICE-1 decision (2026-05-23).
+ *
+ * ASCII-only.
+ */
+export const DEFAULT_VOICEPRINT_CONFIG = {
+    provider: 'local-mfcc-stub',
+    threshold: 0.75,
+    permissive: false,
+};
+//# sourceMappingURL=types.js.map

package/dist/voice/voiceprint/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/voice/voiceprint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA+DH,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,QAAQ,EAAE,iBAAiB;IAC3B,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,KAAK;CAClB,CAAC"}

package/dist/voice/wake.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Wake-word matcher (PLAN soft #8).
+ *
+ * Problem (Pablo 2026-05-26): "Yujin" pronounces as "yu-yin"
+ * in Japanese, but STT providers trained mostly on English
+ * write the audio back as a noisy set of variants:
+ * "yujin" / "yuyin" / "you jin" / "u jin" / "yujín" / etc.
+ *
+ * A literal match against "yujin" would miss most utterances.
+ *
+ * Strategy (A + C combined):
+ *   A. Default alias list covers the variants we know STTs
+ *      emit + Levenshtein distance ≤ 2 catches the rest.
+ *   B. User can extend the alias list per-device via the
+ *      vault slot `wake_aliases` (comma-separated). The
+ *      `yf voice config --aliases X,Y,Z` CLI persists it.
+ *
+ * Pre-processing:
+ *   - lowercase
+ *   - strip accents (NFD + ASCII filter)
+ *   - strip dashes, periods, commas
+ *   - collapse whitespace
+ *
+ * Match algorithm:
+ *   - exact alias match -> hit
+ *   - fuzzy Levenshtein distance 0..2 against any alias -> hit
+ *   - else miss
+ *
+ * The matcher is invoked on the FIRST window of every voice
+ * turn; once it fires, intents.ts takes over for the rest of
+ * the utterance.
+ *
+ * ASCII-only.
+ */
+export declare const DEFAULT_WAKE_ALIASES: readonly string[];
+export interface WakeMatchResult {
+    hit: boolean;
+    /** Alias the matcher hit on (canonical form). */
+    matched_alias?: string;
+    /** Distance from the alias (0 = exact, 1-2 = fuzzy). */
+    distance?: number;
+    /** Normalised version of the input that the matcher saw. */
+    normalised: string;
+}
+export interface WakeMatchOptions {
+    /** Override or extend the default alias set. When provided,
+     *  replaces DEFAULT_WAKE_ALIASES entirely (use mergeAliases
+     *  to combine). */
+    aliases?: readonly string[];
+    /** Maximum Levenshtein distance accepted. Default 2. */
+    maxDistance?: number;
+}
+/** Normalise a transcript chunk so STT noise (accents,
+ *  punctuation, casing) does not block the match. */
+export declare function normaliseWakeInput(input: string): string;
+/** Classic Levenshtein. O(n*m). For wake-word strings (< 20
+ *  chars) the cost is trivial. */
+export declare function levenshtein(a: string, b: string): number;
+/** Run the wake-word matcher against the input. */
+export declare function matchWakeWord(input: string, opts?: WakeMatchOptions): WakeMatchResult;
+/** Merge user-provided aliases with the defaults, dedup +
+ *  normalised. */
+export declare function mergeAliases(extra: readonly string[]): string[];
+//# sourceMappingURL=wake.d.ts.map

package/dist/voice/wake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake.d.ts","sourceRoot":"","sources":["../../src/voice/wake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAcjD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,OAAO,CAAC;IACb,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;uBAEmB;IACnB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;qDACqD;AACrD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASxD;AAED;kCACkC;AAClC,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBxD;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,gBAAqB,GAC1B,eAAe,CAsCjB;AAED;kBACkB;AAClB,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAW/D"}

package/dist/voice/wake.js

@@ -0,0 +1,143 @@
+/**
+ * Wake-word matcher (PLAN soft #8).
+ *
+ * Problem (Pablo 2026-05-26): "Yujin" pronounces as "yu-yin"
+ * in Japanese, but STT providers trained mostly on English
+ * write the audio back as a noisy set of variants:
+ * "yujin" / "yuyin" / "you jin" / "u jin" / "yujín" / etc.
+ *
+ * A literal match against "yujin" would miss most utterances.
+ *
+ * Strategy (A + C combined):
+ *   A. Default alias list covers the variants we know STTs
+ *      emit + Levenshtein distance ≤ 2 catches the rest.
+ *   B. User can extend the alias list per-device via the
+ *      vault slot `wake_aliases` (comma-separated). The
+ *      `yf voice config --aliases X,Y,Z` CLI persists it.
+ *
+ * Pre-processing:
+ *   - lowercase
+ *   - strip accents (NFD + ASCII filter)
+ *   - strip dashes, periods, commas
+ *   - collapse whitespace
+ *
+ * Match algorithm:
+ *   - exact alias match -> hit
+ *   - fuzzy Levenshtein distance 0..2 against any alias -> hit
+ *   - else miss
+ *
+ * The matcher is invoked on the FIRST window of every voice
+ * turn; once it fires, intents.ts takes over for the rest of
+ * the utterance.
+ *
+ * ASCII-only.
+ */
+/* Default aliases we know STTs emit for "Yujin" / "yu-yin".
+ * Accented forms ("yujín", "yuyín") would normalise into the
+ * un-accented variants -- keep only the canonical post-normalise
+ * shapes here so mergeAliases dedup math stays predictable. */
+export const DEFAULT_WAKE_ALIASES = [
+    'yujin',
+    'yuyin',
+    'you jin',
+    'you yin',
+    'u jin',
+    'yu jin',
+    'yu yin',
+    'yoo jin',
+    'yoo yin',
+    'yujim',
+    'yuyim',
+    'yu shin',
+    'you shin',
+];
+/** Normalise a transcript chunk so STT noise (accents,
+ *  punctuation, casing) does not block the match. */
+export function normaliseWakeInput(input) {
+    const lower = input.toLowerCase();
+    /* NFD decomposes accented chars into base + combining mark;
+       the [̀-ͯ] range covers all combining diacritics. */
+    const stripped = lower.normalize('NFD').replace(/[̀-ͯ]/g, '');
+    /* Strip punctuation that STTs sometimes insert. */
+    const noPunct = stripped.replace(/[.,;:!?\-_'"]/g, ' ');
+    /* Collapse whitespace. */
+    return noPunct.replace(/\s+/g, ' ').trim();
+}
+/** Classic Levenshtein. O(n*m). For wake-word strings (< 20
+ *  chars) the cost is trivial. */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    /* Rolling 2-row matrix to keep memory tight. */
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, /* insert */ prev[j] + 1, /* delete */ prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/** Run the wake-word matcher against the input. */
+export function matchWakeWord(input, opts = {}) {
+    const normalised = normaliseWakeInput(input);
+    if (normalised.length === 0) {
+        return { hit: false, normalised };
+    }
+    const aliases = (opts.aliases ?? DEFAULT_WAKE_ALIASES).map((a) => normaliseWakeInput(a));
+    const maxDist = opts.maxDistance ?? 2;
+    /* Build candidates: the full normalised string, every single
+       token, and every contiguous pair of tokens. This catches
+       filler-prefixed utterances like "hey yujin" / "ok yu jin"
+       plus single-word matches when STT misses spaces. */
+    const tokens = normalised.split(' ');
+    const candidates = [normalised];
+    for (let i = 0; i < tokens.length; i++) {
+        candidates.push(tokens[i]);
+        if (i + 1 < tokens.length)
+            candidates.push(tokens[i] + ' ' + tokens[i + 1]);
+    }
+    let best = null;
+    for (const c of candidates) {
+        for (const a of aliases) {
+            const d = levenshtein(c, a);
+            if (d <= maxDist) {
+                if (!best || d < best.distance)
+                    best = { alias: a, distance: d };
+            }
+        }
+    }
+    if (best) {
+        return {
+            hit: true,
+            matched_alias: best.alias,
+            distance: best.distance,
+            normalised,
+        };
+    }
+    return { hit: false, normalised };
+}
+/** Merge user-provided aliases with the defaults, dedup +
+ *  normalised. */
+export function mergeAliases(extra) {
+    const seen = new Set();
+    const out = [];
+    for (const a of [...DEFAULT_WAKE_ALIASES, ...extra]) {
+        const norm = normaliseWakeInput(a);
+        if (norm.length > 0 && !seen.has(norm)) {
+            seen.add(norm);
+            out.push(norm);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=wake.js.map

package/dist/voice/wake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake.js","sourceRoot":"","sources":["../../src/voice/wake.ts"],"names":[],"mappings":"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"}

package/docs/manuals/manual.ar.html

@@ -0,0 +1,91 @@
+<!DOCTYPE html>
+<html lang="ar" dir="rtl">
+<head>
+<meta charset="utf-8">
+<title>Yujin Forge -- دليل المستخدم</title>
+</head>
+<body>
+
+<h1>Yujin Forge -- دليل المستخدم</h1>
+
+<p>مساعد تطوير صوتي أولاً لبناء تطبيقات React + NAC-3. مصمم
+ليتمكن مرافق أو طفل يتعلم البرمجة من تشغيله دون الحاجة إلى
+لمس الطرفية.</p>
+
+<h2>مرحباً</h2>
+
+<p>يقوم Yujin Forge بثلاثة أشياء بسيطة:</p>
+<ul>
+  <li>يقرأ المستندات بصوت عالٍ (PDF، Word، HTML، MD، EPUB،
+      CSV، Excel، الكود المصدري، txt، RTF).</li>
+  <li>يأخذ مواصفات التصميم ويولد كود التطبيق تلقائياً.</li>
+  <li>يتحدث مع مساعد ذكاء اصطناعي يعرف مشروعك: قراءة البيان،
+      البحث في SPEC، تحرير المكونات، إجراء الالتزامات.</li>
+</ul>
+
+<h2>التثبيت</h2>
+
+<ol>
+  <li>قم بتثبيت Node.js 18.17 أو أحدث من nodejs.org.</li>
+  <li>في الطرفية: <pre>npm install -g @yujin/forge-cli@alpha</pre></li>
+  <li>تحقق باستخدام <code>yf --version</code>.</li>
+  <li>قم بتشغيل <code>yf doctor</code>.</li>
+</ol>
+
+<h2>التشغيل الأول</h2>
+
+<pre>yf chat</pre>
+
+<p>يفتح المتصفح لوحة Yujin. انقر فوق زر <strong>المفاتيح</strong>
+وحمّل مفاتيح API. يظهر كل مفتاح مرة واحدة فقط عند إدخاله.</p>
+
+<h2>الأوامر الصوتية</h2>
+
+<p>يفهم Yujin الإسبانية والإنجليزية والبرتغالية والفرنسية
+والألمانية والإيطالية واليابانية والصينية والهندية والعربية.</p>
+
+<table border="1">
+<tr><th>تقول</th><th>ماذا يحدث</th></tr>
+<tr><td>"افتح <em>الملف</em>"</td><td>يفتح المستند.</td></tr>
+<tr><td>"التالي" / "استمر"</td><td>ينتقل إلى الكتلة التالية.</td></tr>
+<tr><td>"ابحث عن <em>كلمة</em>"</td><td>يبحث ويقرأ أول تطابق.</td></tr>
+<tr><td>"علامة هنا باسم <em>اسم</em>"</td><td>يضع علامة مرجعية.</td></tr>
+<tr><td>"انتقل إلى العلامة <em>اسم</em>"</td><td>يعود إلى العلامة.</td></tr>
+<tr><td>"تلخيص"</td><td>يعيد قراءة آخر الكتل.</td></tr>
+<tr><td>"افتح الدليل"</td><td>يفتح هذا الدليل بلغتك.</td></tr>
+</table>
+
+<h2>استيعاب المواصفات</h2>
+
+<p>اسحب ملف مواصفات إلى اللوحة. تظهر شاشة بنفسجية بها كانجي.
+أفلت الملف عليها.</p>
+
+<ol>
+  <li>يقرأ Yujin المستند.</li>
+  <li>يستخرج Claude المتطلبات والكيانات ونقاط النهاية والمكونات.</li>
+  <li>يقدم Claude خطة للملفات المراد إنشاؤها.</li>
+  <li>يعرض Yujin الخطة. قل "موافق".</li>
+  <li>ينشئ الملفات في مجلد مشروعك.</li>
+  <li>إذا حدث خطأ، قل "تراجع".</li>
+</ol>
+
+<h2>حل المشكلات</h2>
+
+<dl>
+  <dt>الميكروفون لا يعمل</dt>
+  <dd>يطلب المتصفح الإذن لأول مرة. انقر فوق القفل بجانب URL.</dd>
+  <dt>لا يفهمني</dt>
+  <dd>حمّل مفتاح OpenAI في خانة <code>openai</code>.</dd>
+  <dt>الصوت سيء</dt>
+  <dd>حمّل مفتاح ElevenLabs للحصول على صوت أكثر طبيعية.</dd>
+  <dt>أريد البدء من جديد</dt>
+  <dd>أغلق Yujin. احذف <code>~/.yujin-forge/</code>.
+      قم بتشغيل <code>yf chat</code> مرة أخرى.</dd>
+</dl>
+
+<h2>الدعم</h2>
+
+<p>الدعم: <a href="mailto:pablo@rpaforce.com">pablo@rpaforce.com</a></p>
+
+</body>
+</html>