@nac3/forge-cli 0.2.0-alpha.1

package/dist/core/mode.js

@@ -0,0 +1,122 @@
+/**
+ * Forge communication mode resolver (SQ 0.8).
+ *
+ * Mode = the level of technical exposure Forge uses when
+ * talking to the user. Two values:
+ *
+ *   didactico -- minimal tech detail, higher autonomy,
+ *                consults only what is strictly necessary.
+ *   tecnico   -- full surface: diffs, tool calls, latencies,
+ *                request ids; involves user in decisions.
+ *
+ * Precedence (highest wins):
+ *   1. YF_MODE env var
+ *   2. CLI flag (passed by callers, e.g. `yf chat --mode X`)
+ *   3. yujin.forge.json::mode in the project
+ *   4. DEFAULT (= didactico)
+ *
+ * Runtime changes (via `/modo` in chat) persist back to
+ * yujin.forge.json so the next launch picks it up.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export const FORGE_MODES = ['didactico', 'tecnico'];
+export const DEFAULT_MODE = 'didactico';
+/** Project-config file at projectRoot. NB: `yf chat` reads
+ *  `yujin.forge.json` already; we extend the same file. */
+const PROJECT_CONFIG = 'yujin.forge.json';
+function normalise(v) {
+    if (typeof v !== 'string')
+        return null;
+    const lower = v.trim().toLowerCase();
+    /* English aliases for the CLI / chat command. */
+    const map = {
+        'didactico': 'didactico',
+        'didactic': 'didactico',
+        'didact': 'didactico',
+        'd': 'didactico',
+        'tecnico': 'tecnico',
+        'tecnica': 'tecnico',
+        'technical': 'tecnico',
+        'tech': 'tecnico',
+        't': 'tecnico',
+    };
+    return map[lower] ?? null;
+}
+/** Resolve the effective mode for a process. */
+export async function resolveMode(opts) {
+    /* 1. env */
+    const envRaw = opts.envValue ?? process.env.YF_MODE;
+    const fromEnv = normalise(envRaw);
+    if (fromEnv)
+        return { mode: fromEnv, source: 'env' };
+    /* 2. CLI */
+    const fromCli = normalise(opts.cliFlag);
+    if (fromCli)
+        return { mode: fromCli, source: 'cli' };
+    /* 3. project config */
+    const cfgPath = path.join(opts.projectRoot, PROJECT_CONFIG);
+    try {
+        const raw = await fs.readFile(cfgPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const fromProject = normalise(parsed.mode);
+        if (fromProject)
+            return { mode: fromProject, source: 'project' };
+    }
+    catch { /* missing or bad -- fall through */ }
+    /* 4. default */
+    return { mode: DEFAULT_MODE, source: 'default' };
+}
+/** Persist `mode` into the project config file, creating it
+ *  if missing. Existing fields are preserved. */
+export async function persistMode(projectRoot, mode) {
+    const cfgPath = path.join(projectRoot, PROJECT_CONFIG);
+    let cfg = {};
+    try {
+        const raw = await fs.readFile(cfgPath, 'utf-8');
+        cfg = JSON.parse(raw);
+        if (!cfg || typeof cfg !== 'object')
+            cfg = {};
+    }
+    catch { /* create fresh */ }
+    cfg.mode = mode;
+    await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2), 'utf-8');
+}
+/** System-prompt suffix that the chat orchestrator injects
+ *  into the Claude system role so the model adapts its tone
+ *  + level of consultation to the user's mode. */
+export function modePromptSuffix(mode) {
+    if (mode === 'didactico') {
+        return [
+            '',
+            'COMMUNICATION MODE: DIDACTIC.',
+            '- Use plain language, oriented at outcomes. Do NOT name',
+            '  files, lines, classes, stack traces, or developer jargon',
+            '  unless the user explicitly asks.',
+            '- Higher autonomy: decide internal technical details on',
+            '  your own; consult the user ONLY when the decision affects',
+            '  what they want to achieve (not how you achieve it).',
+            '- Progress updates summarise the result, not the steps.',
+            '  ("registered the new user", not "wrote app/users.tsx").',
+            '- Errors framed as the next action: "could not read this',
+            '  PDF, want to try another?" -- never raw stack traces.',
+        ].join('\n');
+    }
+    /* tecnico */
+    return [
+        '',
+        'COMMUNICATION MODE: TECHNICAL.',
+        '- Expose the technical surface fully: files touched, lines',
+        '  modified, tool calls dispatched, latencies, tokens, etc.',
+        '- Involve the user in technical decisions: present options',
+        '  with trade-offs (cost, portability, complexity), ask which',
+        '  one to take.',
+        '- Surface diffs before applying irreversible changes.',
+        '- Show stack traces + request ids on errors.',
+        '- Progress updates carry metadata: "scaffolded',
+        '  `app/register.tsx`, 42 lines, 3 components".',
+    ].join('\n');
+}
+//# sourceMappingURL=mode.js.map

package/dist/core/mode.js.map

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

package/dist/core/pairing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Mobile pairing protocol -- CLI side.
+ *
+ * Mirrors packages/nac3-rn/src/pairing.ts byte-for-byte on the
+ * crypto helpers (generatePairingCode / validatePairingCode /
+ * encryptPairing / decryptPairing / envelope helpers). The
+ * mobile side lives in the nac3-rn package; this copy is for
+ * the CLI which cannot import out-of-rootDir.
+ *
+ * Drift between the two sides is caught by
+ * tests/pairing-cross-impl.test.ts which encrypts on one side
+ * + decrypts on the other.
+ *
+ * ASCII-only. WebCrypto-only -- runs identically on Node 20+
+ * and React Native.
+ */
+export interface PairingPayload {
+    user_handle: string;
+    server_api_key: string;
+    hito4_base_url: string;
+    expires_at: string;
+    meta?: Record<string, unknown>;
+}
+export interface PairingEnvelope {
+    v: 1;
+    salt: string;
+    iv: string;
+    ct: string;
+}
+export declare function generatePairingCode(): string;
+export declare function validatePairingCode(code: string): boolean;
+export declare function encryptPairing(payload: PairingPayload, code: string): Promise<PairingEnvelope>;
+export declare class PairingDecryptError extends Error {
+    readonly kind: 'bad_code' | 'expired' | 'malformed';
+    constructor(kind: 'bad_code' | 'expired' | 'malformed');
+}
+export declare function decryptPairing(envelope: PairingEnvelope, code: string): Promise<PairingPayload>;
+export declare function envelopeToQrString(env: PairingEnvelope): string;
+export declare function envelopeFromQrString(s: string): PairingEnvelope;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/core/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/core/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AA0BD,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAeD,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GACpC,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW;gBAA1C,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW;CAGvE;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GACtC,OAAO,CAAC,cAAc,CAAC,CA+BzB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE/D;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAmB/D"}

package/dist/core/pairing.js

@@ -0,0 +1,145 @@
+/**
+ * Mobile pairing protocol -- CLI side.
+ *
+ * Mirrors packages/nac3-rn/src/pairing.ts byte-for-byte on the
+ * crypto helpers (generatePairingCode / validatePairingCode /
+ * encryptPairing / decryptPairing / envelope helpers). The
+ * mobile side lives in the nac3-rn package; this copy is for
+ * the CLI which cannot import out-of-rootDir.
+ *
+ * Drift between the two sides is caught by
+ * tests/pairing-cross-impl.test.ts which encrypts on one side
+ * + decrypts on the other.
+ *
+ * ASCII-only. WebCrypto-only -- runs identically on Node 20+
+ * and React Native.
+ */
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+const PBKDF2_ITERS = 200_000;
+const KEY_BITS = 256;
+const IV_BYTES = 12;
+const SALT_BYTES = 16;
+function bufToHex(buf) {
+    const view = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    let hex = '';
+    for (let i = 0; i < view.length; i++)
+        hex += view[i].toString(16).padStart(2, '0');
+    return hex;
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error('pairing: hex string has odd length');
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            throw new Error('pairing: invalid hex');
+        out[i] = byte;
+    }
+    return out;
+}
+function randomBytes(n) {
+    const out = new Uint8Array(n);
+    crypto.getRandomValues(out);
+    return out;
+}
+export function generatePairingCode() {
+    const n = Math.floor(Math.random() * 1_000_000);
+    return n.toString(10).padStart(6, '0');
+}
+export function validatePairingCode(code) {
+    return typeof code === 'string' && /^\d{6}$/.test(code);
+}
+async function deriveKey(code, salt) {
+    const baseKey = await crypto.subtle.importKey('raw', ENC.encode(code), { name: 'PBKDF2' }, false, ['deriveKey']);
+    return crypto.subtle.deriveKey({ name: 'PBKDF2', salt: salt, iterations: PBKDF2_ITERS, hash: 'SHA-256' }, baseKey, { name: 'AES-GCM', length: KEY_BITS }, false, ['encrypt', 'decrypt']);
+}
+export async function encryptPairing(payload, code) {
+    if (!validatePairingCode(code))
+        throw new Error('pairing: invalid code');
+    const salt = randomBytes(SALT_BYTES);
+    const iv = randomBytes(IV_BYTES);
+    const key = await deriveKey(code, salt);
+    const plain = ENC.encode(JSON.stringify(payload));
+    const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain);
+    return {
+        v: 1,
+        salt: bufToHex(salt),
+        iv: bufToHex(iv),
+        ct: bufToHex(new Uint8Array(ct)),
+    };
+}
+export class PairingDecryptError extends Error {
+    kind;
+    constructor(kind) {
+        super('pairing: ' + kind);
+        this.kind = kind;
+    }
+}
+export async function decryptPairing(envelope, code) {
+    if (!validatePairingCode(code))
+        throw new PairingDecryptError('bad_code');
+    if (envelope.v !== 1)
+        throw new PairingDecryptError('malformed');
+    let salt;
+    let iv;
+    let ct;
+    try {
+        salt = hexToBytes(envelope.salt);
+        iv = hexToBytes(envelope.iv);
+        ct = hexToBytes(envelope.ct);
+    }
+    catch {
+        throw new PairingDecryptError('malformed');
+    }
+    const key = await deriveKey(code, salt);
+    let plain;
+    try {
+        plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
+    }
+    catch {
+        throw new PairingDecryptError('bad_code');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(DEC.decode(plain));
+    }
+    catch {
+        throw new PairingDecryptError('malformed');
+    }
+    if (!parsed.user_handle || !parsed.server_api_key || !parsed.expires_at) {
+        throw new PairingDecryptError('malformed');
+    }
+    if (Date.parse(parsed.expires_at) < Date.now()) {
+        throw new PairingDecryptError('expired');
+    }
+    return parsed;
+}
+export function envelopeToQrString(env) {
+    return 'yfpair://' + Buffer.from(JSON.stringify(env), 'utf-8').toString('base64url');
+}
+export function envelopeFromQrString(s) {
+    if (!s.startsWith('yfpair://'))
+        throw new PairingDecryptError('malformed');
+    const b64 = s.slice('yfpair://'.length);
+    let json;
+    try {
+        json = Buffer.from(b64, 'base64url').toString('utf-8');
+    }
+    catch {
+        throw new PairingDecryptError('malformed');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new PairingDecryptError('malformed');
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.v !== 1) {
+        throw new PairingDecryptError('malformed');
+    }
+    return parsed;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/core/pairing.js.map

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

package/dist/core/pilot_setup.d.ts

@@ -0,0 +1,29 @@
+export interface PilotSetupState {
+    pilot_completed: boolean;
+    target_pending: boolean;
+    mode_pending: boolean;
+}
+/** Read the current pilot setup state. */
+export declare function readPilotState(projectRoot: string): Promise<PilotSetupState>;
+/** Mark Pilot setup as completed (also bumps the persisted
+ *  yujin.forge.json with default values if any are missing). */
+export declare function completePilotSetup(projectRoot: string, defaults?: {
+    target?: string;
+    mode?: string;
+}): Promise<void>;
+/** System-prompt addendum that asks the user about target
+ *  + mode in plain prose. Injected by buildSystemPrompt when
+ *  pilot_completed is false. */
+export declare function welcomePromptSuffix(state: PilotSetupState): string;
+/** Decide whether to mark setup as complete after the first
+ *  reply. Heuristic: if the user has answered both questions
+ *  OR has skipped them by talking about something else, we
+ *  flag completed (with defaults).
+ *
+ *  The actual answer detection lives in the chat handler
+ *  side; this function only encodes the decision shape. */
+export declare function shouldAutoComplete(state: PilotSetupState, userMessage: string): {
+    complete: boolean;
+    reason: 'answered' | 'unrelated' | 'pending';
+};
+//# sourceMappingURL=pilot_setup.d.ts.map

package/dist/core/pilot_setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pilot_setup.d.ts","sourceRoot":"","sources":["../../src/core/pilot_setup.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAG,OAAO,CAAC;IACzB,YAAY,EAAK,OAAO,CAAC;CAC1B;AAED,0CAA0C;AAC1C,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBlF;AAED;gEACgE;AAChE,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;gCAEgC;AAChC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAqBlE;AAED;;;;;;2DAM2D;AAC3D,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,WAAW,EAAE,MAAM,GAClB;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAAA;CAAE,CAkBrE"}

package/dist/core/pilot_setup.js

@@ -0,0 +1,119 @@
+/**
+ * Pilot first-run setup (SQ 0.7 + 0.8 + 0.10 integration).
+ *
+ * When a user starts `yf chat` on a fresh project, Pilot
+ * MUST ask -- in natural language -- two questions:
+ *   1. target (responsive | mobile-only | desktop-only)
+ *   2. mode (didactico | tecnico)
+ *
+ * Per Pablo's decision (2026-05-26): use the chat-natural
+ * style (Option B) with a default-silencioso fallback. If
+ * the user replies about something else entirely, Forge
+ * defaults to `responsive` + `didactico` and continues --
+ * never blocks the conversation.
+ *
+ * State lives in `yujin.forge.json::pilot_completed` (boolean).
+ * Once true, the welcome prompt is skipped.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const CONFIG = 'yujin.forge.json';
+/** Read the current pilot setup state. */
+export async function readPilotState(projectRoot) {
+    try {
+        const raw = await fs.readFile(path.join(projectRoot, CONFIG), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') {
+            return { pilot_completed: false, target_pending: true, mode_pending: true };
+        }
+        const completed = parsed.pilot_completed === true;
+        return {
+            pilot_completed: completed,
+            target_pending: !parsed.target,
+            mode_pending: !parsed.mode,
+        };
+    }
+    catch {
+        return { pilot_completed: false, target_pending: true, mode_pending: true };
+    }
+}
+/** Mark Pilot setup as completed (also bumps the persisted
+ *  yujin.forge.json with default values if any are missing). */
+export async function completePilotSetup(projectRoot, defaults = {}) {
+    const cfgPath = path.join(projectRoot, CONFIG);
+    let cfg = {};
+    try {
+        const raw = await fs.readFile(cfgPath, 'utf-8');
+        cfg = JSON.parse(raw);
+        if (!cfg || typeof cfg !== 'object')
+            cfg = {};
+    }
+    catch { /* fresh */ }
+    cfg.pilot_completed = true;
+    if (!cfg.target && defaults.target)
+        cfg.target = defaults.target;
+    if (!cfg.mode && defaults.mode)
+        cfg.mode = defaults.mode;
+    /* Defaults of the defaults: responsive + didactico. */
+    if (!cfg.target)
+        cfg.target = 'responsive';
+    if (!cfg.mode)
+        cfg.mode = 'didactico';
+    await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2), 'utf-8');
+}
+/** System-prompt addendum that asks the user about target
+ *  + mode in plain prose. Injected by buildSystemPrompt when
+ *  pilot_completed is false. */
+export function welcomePromptSuffix(state) {
+    if (state.pilot_completed)
+        return '';
+    const asks = [];
+    if (state.target_pending) {
+        asks.push('* la app, la queres responsive (desktop + mobile), solo mobile, o solo desktop?');
+    }
+    if (state.mode_pending) {
+        asks.push('* preferis que te hable en lenguaje simple (didactico) o que te muestre todos los detalles tecnicos (tecnico)?');
+    }
+    return [
+        '',
+        'FIRST-RUN PILOT SETUP (this is the first chat in this project).',
+        'On your very first reply, before answering the user, ask -- with one',
+        'short friendly sentence each -- the following:',
+        ...asks,
+        '',
+        'If the user answers, persist via the /api/forge/target and',
+        '/api/forge/mode endpoints. If the user ignores the questions and',
+        'replies about something else, DO NOT insist -- continue with the',
+        'task they care about, and silently default to responsive + didactico.',
+    ].join('\n');
+}
+/** Decide whether to mark setup as complete after the first
+ *  reply. Heuristic: if the user has answered both questions
+ *  OR has skipped them by talking about something else, we
+ *  flag completed (with defaults).
+ *
+ *  The actual answer detection lives in the chat handler
+ *  side; this function only encodes the decision shape. */
+export function shouldAutoComplete(state, userMessage) {
+    if (state.pilot_completed)
+        return { complete: true, reason: 'answered' };
+    const lower = userMessage.toLowerCase();
+    /* "Did the user mention target?" */
+    const targetKeywords = ['mobile', 'desktop', 'responsive', 'movil', 'celular', 'web', 'rn',
+        'react native', 'expo', 'pwa', 'ambos'];
+    const modeKeywords = ['didactico', 'didactic', 'tecnico', 'technical', 'modo'];
+    const mentionsTarget = targetKeywords.some((k) => lower.includes(k));
+    const mentionsMode = modeKeywords.some((k) => lower.includes(k));
+    if (mentionsTarget && mentionsMode) {
+        return { complete: true, reason: 'answered' };
+    }
+    /* If the user wrote >= 30 chars about something else, it's
+     * "unrelated" -> default silencioso. */
+    if (userMessage.trim().length >= 30 && !mentionsTarget && !mentionsMode) {
+        return { complete: true, reason: 'unrelated' };
+    }
+    return { complete: false, reason: 'pending' };
+}
+//# sourceMappingURL=pilot_setup.js.map

package/dist/core/pilot_setup.js.map

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

package/dist/core/polar.d.ts

@@ -0,0 +1,81 @@
+/**
+ * License plans. Public-facing tiers: 'trial', 'paid',
+ * 'cancelled', 'free-public'. Internal-only (NOT advertised
+ * as a marketing tier): 'institutional' (Yujin grants to
+ * institutions), 'gifted' (other accommodations including
+ * but not limited to discapacidad).
+ *
+ * Billing model (Pablo 2026-05-26): TC captured at signup +
+ * 7 days free to cancel + day 8 = first charge. Implemented
+ * via Polar's `trial_period_days: 7` feature.
+ */
+export type LicensePlan = 'none' | 'trial' | 'paid' | 'cancelled' | 'free-public' | 'institutional' | 'gifted';
+export interface LicenseCache {
+    version: 1;
+    plan: LicensePlan;
+    /** When the user attached the payment method (= start of
+     *  the 7-day free cancel window). */
+    trial_started_at?: string;
+    /** When Polar will charge the first month (= trial_started_at + 7d). */
+    bills_first_on?: string;
+    /** Last day the user can cancel without being charged. */
+    cancel_grace_until?: string;
+    /** Polar subscription id (when plan in {trial, paid, cancelled}). */
+    subscription_id?: string;
+    /** Polar confirmed a payment method on file. */
+    payment_method_attached?: boolean;
+    /** Last successful server-side validation. */
+    last_validated_at?: string;
+    /** User-visible identifier (email / username). */
+    user_handle?: string;
+    /** ISO 8601 expiry for paid / cancelled / free-public.
+     *  Null for institutional / gifted (perpetual until revoked). */
+    expires_at?: string | null;
+}
+/** Polar checkout URL -- the live checkout link for the
+ *  Yujin Forge $10/mo subscription. Env override stays so devs
+ *  can point at a test link without rebuilding.
+ *
+ *  Polar checkout links accept `?customer_external_id=<handle>`
+ *  as a query param -- buildCheckoutUrl appends it -- and the
+ *  value persists into the subscription metadata, which the
+ *  HITO 4 webhook handler reads via
+ *  metadata.customer_external_id (with email fallback). */
+export declare const POLAR_CHECKOUT_BASE: string;
+/** Build a Polar checkout URL with the user's handle as a
+ *  metadata field so we can correlate the subscription back
+ *  to their license. */
+export declare function buildCheckoutUrl(userHandle?: string): string;
+/** Read the cached license. Returns a 'none' entry when no
+ *  payment method has been captured yet -- the user is
+ *  redirected to the Polar checkout. NO automatic trial
+ *  seeding (TC-upfront model). */
+export declare function readLicense(): Promise<LicenseCache>;
+/** Persist the license cache. */
+export declare function writeLicense(cache: LicenseCache): Promise<void>;
+/** Helper: build a fresh trial license once the user
+ *  attaches a payment method (typically called from the
+ *  Polar webhook handler on `checkout.session.completed`). */
+export declare function buildTrialLicense(opts: {
+    subscription_id: string;
+    user_handle?: string;
+    trial_days?: number;
+}): LicenseCache;
+/** Is the license currently active? Active = the user can
+ *  use Forge right now. Includes trial (in grace), paid,
+ *  cancelled-but-still-in-billing-period, institutional,
+ *  gifted, and free-public. Excludes 'none' (no TC) and
+ *  expired plans. */
+export declare function isActive(cache: LicenseCache): boolean;
+/** Days until the user gets charged (trial) or expires
+ *  (paid/cancelled). Null when the plan has no time clock. */
+export declare function daysUntilBillingOrExpiry(cache: LicenseCache): number | null;
+/** Back-compat alias kept so existing callers don't break. */
+export declare function daysRemaining(cache: LicenseCache): number | null;
+/** Surface for `yf doctor` and the chat panel. ASCII-only.
+ *  Internal-only plans (institutional, gifted) DO NOT
+ *  surface the underlying reason -- they show a generic
+ *  "free seat" message. Pablo's policy: no advertising
+ *  discapacidad as a tier. */
+export declare function describeLicense(cache: LicenseCache): string;
+//# sourceMappingURL=polar.d.ts.map

package/dist/core/polar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polar.d.ts","sourceRoot":"","sources":["../../src/core/polar.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,OAAO,GACP,MAAM,GACN,WAAW,GACX,aAAa,GACb,eAAe,GACf,QAAQ,CAAC;AAEb,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB;yCACqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;qEACiE;IACjE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAID;;;;;;;;2DAQ2D;AAC3D,eAAO,MAAM,mBAAmB,QAE6C,CAAC;AAE9E;;wBAEwB;AACxB,wBAAgB,gBAAgB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5D;AAOD;;;kCAGkC;AAClC,wBAAsB,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC,CAWzD;AAED,iCAAiC;AACjC,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;8DAE8D;AAC9D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,CAcf;AAED;;;;qBAIqB;AACrB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAarD;AAED;8DAC8D;AAC9D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAO3E;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;8BAI8B;AAC9B,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA6B3D"}