@nac3/forge-cli 0.2.0-alpha.1

package/dist/core/polar.js

@@ -0,0 +1,175 @@
+/**
+ * Polar billing integration (PLAN connectivity #2 -- $10/mo).
+ *
+ * Polar.sh is the chosen payment processor: instant TC
+ * charge, no Stripe friction, ~3% + $0.30/transaction.
+ *
+ * Forge clients consult `prompts.yujin.app/api/v1/license`
+ * (HITO 4 territory) for current paid status. This module
+ * gives the local-side primitives:
+ *
+ *   - Plan type definition (paid / free-disability / trial).
+ *   - License cache + read/write to `~/.yujin-forge/license.json`.
+ *   - URL generator for the Polar checkout flow.
+ *   - validateLicense() probes the central server (eventual).
+ *
+ * Real signing + verification land when HITO 4 server
+ * exists. For now, the module ships:
+ *   - in-memory + on-disk cache shape
+ *   - the URL pattern that the chat panel surfaces when the
+ *     user is on trial / expired
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const LICENSE_FILE = 'license.json';
+/** 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 const POLAR_CHECKOUT_BASE = process.env.YF_POLAR_CHECKOUT_URL ??
+    'https://buy.polar.sh/polar_cl_hy6ndD0QpqBnJ8qM2HQPrxZekiIsijW1VQLIf2Y8AHa';
+/** 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 function buildCheckoutUrl(userHandle) {
+    const url = new URL(POLAR_CHECKOUT_BASE);
+    if (userHandle)
+        url.searchParams.set('customer_external_id', userHandle);
+    return url.toString();
+}
+/** Path to ~/.yujin-forge/license.json. */
+function licenseFile() {
+    return path.join(os.homedir(), '.yujin-forge', LICENSE_FILE);
+}
+/** 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 async function readLicense() {
+    const file = licenseFile();
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && parsed.version === 1 && parsed.plan)
+            return parsed;
+    }
+    catch { /* fall through */ }
+    /* First-run: no payment method on file. yf chat is gated. */
+    const none = { version: 1, plan: 'none' };
+    await writeLicense(none);
+    return none;
+}
+/** Persist the license cache. */
+export async function writeLicense(cache) {
+    const file = licenseFile();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = file + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(cache, null, 2), 'utf-8');
+    await fs.rename(tmp, file);
+}
+/** 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 function buildTrialLicense(opts) {
+    const trialDays = opts.trial_days ?? 7;
+    const now = new Date();
+    const firstBill = new Date(now.getTime() + trialDays * 24 * 3600 * 1000);
+    return {
+        version: 1,
+        plan: 'trial',
+        trial_started_at: now.toISOString(),
+        bills_first_on: firstBill.toISOString(),
+        cancel_grace_until: firstBill.toISOString(),
+        subscription_id: opts.subscription_id,
+        payment_method_attached: true,
+        ...(opts.user_handle ? { user_handle: opts.user_handle } : {}),
+    };
+}
+/** 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 function isActive(cache) {
+    if (cache.plan === 'none')
+        return false;
+    if (cache.plan === 'institutional' || cache.plan === 'gifted')
+        return true;
+    if (cache.plan === 'free-public')
+        return true;
+    if (cache.plan === 'trial') {
+        if (!cache.cancel_grace_until)
+            return false;
+        return new Date(cache.cancel_grace_until).getTime() > Date.now();
+    }
+    if (cache.plan === 'paid' || cache.plan === 'cancelled') {
+        if (!cache.expires_at)
+            return cache.plan === 'paid';
+        return new Date(cache.expires_at).getTime() > Date.now();
+    }
+    return false;
+}
+/** Days until the user gets charged (trial) or expires
+ *  (paid/cancelled). Null when the plan has no time clock. */
+export function daysUntilBillingOrExpiry(cache) {
+    const target = cache.plan === 'trial'
+        ? cache.cancel_grace_until
+        : cache.expires_at;
+    if (!target)
+        return null;
+    const ms = new Date(target).getTime() - Date.now();
+    return Math.floor(ms / (24 * 3600 * 1000));
+}
+/** Back-compat alias kept so existing callers don't break. */
+export function daysRemaining(cache) {
+    return daysUntilBillingOrExpiry(cache);
+}
+/** 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 function describeLicense(cache) {
+    if (cache.plan === 'none') {
+        return 'no payment method on file. Run `yf license activate` to add a card + start the 7-day free window.';
+    }
+    if (cache.plan === 'institutional' || cache.plan === 'gifted') {
+        return 'free seat -- thanks for being part of Yujin.';
+    }
+    if (cache.plan === 'free-public')
+        return 'free (public repos only)';
+    const days = daysUntilBillingOrExpiry(cache);
+    if (cache.plan === 'trial') {
+        if (days === null)
+            return 'trial -- missing dates';
+        if (days < 0) {
+            return 'trial -- charged on day 8. Run `yf license status` for the next bill date.';
+        }
+        if (days === 0)
+            return 'trial -- last day to cancel sin cargo. Bills tomorrow.';
+        return 'trial -- ' + days + ' days left to cancel sin cargo. Day ' + (8 - days) + ' bills USD 10.';
+    }
+    if (cache.plan === 'paid') {
+        if (days === null)
+            return 'paid -- next bill date unknown';
+        if (days < 0)
+            return 'paid -- expired ' + Math.abs(days) + ' days ago';
+        return 'paid -- next bill in ' + days + ' day(s)';
+    }
+    if (cache.plan === 'cancelled') {
+        if (days === null || days < 0) {
+            return 'cancelled. Run `yf license resubscribe` to reactivate.';
+        }
+        return 'cancelled -- access ends in ' + days + ' day(s). Run `yf license resubscribe` to keep it.';
+    }
+    return 'unknown plan';
+}
+//# sourceMappingURL=polar.js.map

package/dist/core/polar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polar.js","sourceRoot":"","sources":["../../src/core/polar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AA6CzB,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC;;;;;;;;2DAQ2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAC9B,OAAO,CAAC,GAAG,CAAC,qBAAqB;IACjC,2EAA2E,CAAC;AAE9E;;wBAEwB;AACxB,MAAM,UAAU,gBAAgB,CAAC,UAAmB;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACzC,IAAI,UAAU;QAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,sBAAsB,EAAE,UAAU,CAAC,CAAC;IACzE,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED,2CAA2C;AAC3C,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;AAC/D,CAAC;AAED;;;kCAGkC;AAClC,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI;YAAE,OAAO,MAAsB,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,MAAM,IAAI,GAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACxD,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iCAAiC;AACjC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAmB;IACpD,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACjE,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;8DAE8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,IAIjC;IACC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IACzE,OAAO;QACL,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,GAAG,CAAC,WAAW,EAAE;QACnC,cAAc,EAAE,SAAS,CAAC,WAAW,EAAE;QACvC,kBAAkB,EAAE,SAAS,CAAC,WAAW,EAAE;QAC3C,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,uBAAuB,EAAE,IAAI;QAC7B,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;qBAIqB;AACrB,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,kBAAkB;YAAE,OAAO,KAAK,CAAC;QAC5C,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACnE,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACxD,IAAI,CAAC,KAAK,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;QACpD,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;8DAC8D;AAC9D,MAAM,UAAU,wBAAwB,CAAC,KAAmB;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO;QACnC,CAAC,CAAC,KAAK,CAAC,kBAAkB;QAC1B,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;IACrB,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,OAAO,wBAAwB,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;8BAI8B;AAC9B,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,mGAAmG,CAAC;IAC7G,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9D,OAAO,8CAA8C,CAAC;IACxD,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,0BAA0B,CAAC;IACpE,MAAM,IAAI,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,wBAAwB,CAAC;QACnD,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,4EAA4E,CAAC;QACtF,CAAC;QACD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,wDAAwD,CAAC;QAChF,OAAO,WAAW,GAAG,IAAI,GAAG,sCAAsC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,gBAAgB,CAAC;IACrG,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,gCAAgC,CAAC;QAC3D,IAAI,IAAI,GAAG,CAAC;YAAE,OAAO,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC;QACvE,OAAO,uBAAuB,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,wDAAwD,CAAC;QAClE,CAAC;QACD,OAAO,8BAA8B,GAAG,IAAI,GAAG,mDAAmD,CAAC;IACrG,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/core/project_picker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Project picker -- merges three sources into the unified set
+ * a mobile / sibling-laptop UI shows when the user wants to
+ * choose a project to work on:
+ *
+ *   1. Local registry projects (this device's known projects).
+ *   2. yujin-state remote projects (pulled via projects_sync).
+ *   3. mDNS-discovered laptops on the LAN (active sessions).
+ *
+ * The merge produces a ranked + deduplicated list of
+ * `PickerEntry` objects with:
+ *   - slug                 (canonical id)
+ *   - source: 'local' | 'remote_only' | 'lan_session'
+ *   - localPath?           (when this device has a checkout)
+ *   - lanHost? / lanPort?  (when mDNS saw it announcing)
+ *   - lastActiveAt?        (for sort order)
+ *
+ * The shell uses the source to drive iconography + UX:
+ *   local         -> "open"
+ *   lan_session   -> "join session"  (laptop is running yf chat)
+ *   remote_only   -> "clone" or "request access"
+ *
+ * Pure -- merges inputs, does not perform I/O.
+ *
+ * ASCII-only.
+ */
+import type { ProjectEntry } from './projects.js';
+import type { Discovery as LanDiscovery } from '../lan/mdns_service.js';
+export type PickerSource = 'local' | 'lan_session' | 'remote_only';
+export interface PickerEntry {
+    slug: string;
+    source: PickerSource;
+    /** Sort timestamp (ISO 8601). `lan_session` always wins
+     *  the tie against `local` (live > cached). */
+    lastActiveAt?: string;
+    /** Absolute path on this device, when applicable. */
+    localPath?: string;
+    /** mDNS-resolved host/port for live sessions. */
+    lanHost?: string;
+    lanPort?: number;
+    /** Repo URL (when known). */
+    githubRepo?: string;
+    /** Build / slug metadata from the mDNS TXT record. */
+    lanTxt?: Record<string, string>;
+}
+export interface PickerInputs {
+    localProjects: ProjectEntry[];
+    lanDiscoveries?: LanDiscovery[];
+}
+export declare function pickProjects(inputs: PickerInputs): PickerEntry[];
+/** Convenience: given the merged list + the explicit active
+ *  slug, return the entry that should be selected by default
+ *  on first render. If no active slug, return the top-ranked
+ *  entry; if empty, null. */
+export declare function defaultActive(entries: PickerEntry[], activeSlug: string | null): PickerEntry | null;
+//# sourceMappingURL=project_picker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project_picker.d.ts","sourceRoot":"","sources":["../../src/core/project_picker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB;mDAC+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;CACjC;AAsBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,EAAE,CAiDhE;AAED;;;6BAG6B;AAC7B,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,EAAE,EACtB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,WAAW,GAAG,IAAI,CAOpB"}

package/dist/core/project_picker.js

@@ -0,0 +1,86 @@
+/** Rank function: higher = appears first.
+ *
+ *   Layered encoding -- source weight is the dominant term
+ *   (multiplied by 1e16 so it always outranks any timestamp),
+ *   timestamp tiebreaks WITHIN each source tier.
+ *
+ *   lan_session  always beats local + remote_only.
+ *   local        always beats remote_only.
+ *   Within a tier, recent lastActiveAt wins. */
+function rankOf(e) {
+    const sourceWeight = e.source === 'lan_session' ? 3 :
+        e.source === 'local' ? 2 :
+            /* remote_only */ 1;
+    const ts = e.lastActiveAt ? Date.parse(e.lastActiveAt) : 0;
+    /* 1e16 > Number.MAX_SAFE_INTEGER would lose precision; use
+     * 1e15 which is ~ 31000 years past epoch in ms -- safe. */
+    return sourceWeight * 1e15 + ts;
+}
+export function pickProjects(inputs) {
+    const bySlug = new Map();
+    /* Step 1: seed from local registry. */
+    for (const p of inputs.localProjects) {
+        const entry = {
+            slug: p.slug,
+            source: p.remote_only ? 'remote_only' : 'local',
+        };
+        if (!p.remote_only)
+            entry.localPath = p.path;
+        if (p.last_active_at)
+            entry.lastActiveAt = p.last_active_at;
+        if (p.github_repo)
+            entry.githubRepo = p.github_repo;
+        bySlug.set(p.slug, entry);
+    }
+    /* Step 2: overlay LAN discoveries -- they outrank everything
+     *  while they are live. The instance label IS the slug. */
+    for (const d of inputs.lanDiscoveries ?? []) {
+        const slug = d.txt.slug ?? d.instance;
+        const existing = bySlug.get(slug);
+        if (existing) {
+            existing.source = 'lan_session';
+            existing.lanHost = d.host;
+            existing.lanPort = d.port;
+            existing.lanTxt = d.txt;
+            /* If LAN provides a timestamp via TXT, prefer it. */
+            if (d.txt.last_active_at)
+                existing.lastActiveAt = d.txt.last_active_at;
+        }
+        else {
+            bySlug.set(slug, {
+                slug,
+                source: 'lan_session',
+                lanHost: d.host,
+                lanPort: d.port,
+                lanTxt: d.txt,
+                lastActiveAt: d.txt.last_active_at,
+            });
+        }
+    }
+    /* Step 3: sort by rank descending. Tie-break by slug asc for
+     *  deterministic output (helps testing + the UI). */
+    const out = [...bySlug.values()];
+    out.sort((a, b) => {
+        const ra = rankOf(a);
+        const rb = rankOf(b);
+        if (rb !== ra)
+            return rb - ra;
+        return a.slug.localeCompare(b.slug);
+    });
+    return out;
+}
+/** Convenience: given the merged list + the explicit active
+ *  slug, return the entry that should be selected by default
+ *  on first render. If no active slug, return the top-ranked
+ *  entry; if empty, null. */
+export function defaultActive(entries, activeSlug) {
+    if (entries.length === 0)
+        return null;
+    if (activeSlug) {
+        const hit = entries.find((e) => e.slug === activeSlug);
+        if (hit)
+            return hit;
+    }
+    return entries[0] ?? null;
+}
+//# sourceMappingURL=project_picker.js.map

package/dist/core/project_picker.js.map

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

package/dist/core/projects.d.ts

@@ -0,0 +1,58 @@
+export interface ProjectEntry {
+    /** Stable identifier. Derived from yujin.forge.json or
+     *  from the repo name when none is present. */
+    slug: string;
+    /** Absolute path on this device (Windows or POSIX). */
+    path: string;
+    /** Remote repo URL when known (https://github.com/org/repo). */
+    github_repo?: string;
+    /** Last time this device opened this project, ISO 8601. */
+    last_active_at?: string;
+    /** Cached target + mode from yujin.forge.json. */
+    target?: string;
+    mode?: string;
+    /** True if this device cached the entry from GitHub-anchored
+     *  state (i.e. the user knows the slug but the path on
+     *  this device is `null`). */
+    remote_only?: boolean;
+    /** Last-modified ISO 8601 timestamp -- updated on every
+     *  upsertProject. Used for last-writer-wins merge in
+     *  projects_sync.ts. */
+    updated_at?: string;
+}
+export interface ProjectsRegistry {
+    version: 1;
+    /** Slug of the currently-active project on this device. */
+    active_slug: string | null;
+    projects: ProjectEntry[];
+}
+/** Resolve the path to the per-user registry directory. */
+export declare function registryDir(): string;
+/** Read the local registry. Returns empty default when the
+ *  file does not exist. */
+export declare function readRegistry(): Promise<ProjectsRegistry>;
+/** Persist the registry atomically. */
+export declare function writeRegistry(reg: ProjectsRegistry): Promise<void>;
+/** Add or update a project entry. Identified by slug; if the
+ *  slug exists, merges fields (last_active_at + cached fields
+ *  win on update; path stays unless explicitly replaced). */
+export declare function upsertProject(entry: ProjectEntry): Promise<ProjectsRegistry>;
+/** Remove a project from the local registry. Does NOT delete
+ *  the repo on disk. */
+export declare function removeProject(slug: string): Promise<ProjectsRegistry>;
+/** Mark a project as active. Returns the new registry +
+ *  updates last_active_at on the targeted entry. */
+export declare function setActive(slug: string): Promise<ProjectsRegistry>;
+/** Get the slug of the currently-active project (or null). */
+export declare function activeSlug(): Promise<string | null>;
+/** Look up a project entry by slug. */
+export declare function getProject(slug: string): Promise<ProjectEntry | undefined>;
+/** Read the project's yujin.forge.json + derive a slug from
+ *  it (project.slug field, or fall back to the directory
+ *  basename). */
+export declare function deriveSlugFromPath(projectPath: string): Promise<string>;
+/** Scan a directory tree for `yujin.forge.json` files +
+ *  return their parent dirs. Skips node_modules, .git, dist.
+ *  Depth-limited to avoid pathological FS layouts. */
+export declare function scanForProjects(scanRoot: string, maxDepth?: number): Promise<string[]>;
+//# sourceMappingURL=projects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/core/projects.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,YAAY;IAC3B;mDAC+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;kCAE8B;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;4BAEwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,2DAA2D;IAC3D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAID,2DAA2D;AAC3D,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;2BAC2B;AAC3B,wBAAsB,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAU9D;AAED,uCAAuC;AACvC,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxE;AAED;;6DAE6D;AAC7D,wBAAsB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAWlF;AAED;wBACwB;AACxB,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAM3E;AAED;oDACoD;AACpD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQvE;AAED,8DAA8D;AAC9D,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGzD;AAED,uCAAuC;AACvC,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAGhF;AAED;;iBAEiB;AACjB,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU7E;AAED;;sDAEsD;AACtD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBnB"}

package/dist/core/projects.js

@@ -0,0 +1,146 @@
+/**
+ * Project registry (PLAN #10, GitHub-anchored).
+ *
+ * Each device keeps a local cache of known Yujin projects:
+ *   ~/.yujin-forge/projects.json
+ *
+ * The truth-bus is GitHub: the user's `yujin-state` repo
+ * stores authoritative metadata that other devices can pull.
+ * This module exposes only the LOCAL store; GitHub sync
+ * lives in `projects_sync.ts`.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const REGISTRY_FILE = 'projects.json';
+/** Resolve the path to the per-user registry directory. */
+export function registryDir() {
+    return path.join(os.homedir(), '.yujin-forge');
+}
+/** Read the local registry. Returns empty default when the
+ *  file does not exist. */
+export async function readRegistry() {
+    const file = path.join(registryDir(), REGISTRY_FILE);
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && parsed.version === 1 && Array.isArray(parsed.projects)) {
+            return parsed;
+        }
+    }
+    catch { /* fall through */ }
+    return { version: 1, active_slug: null, projects: [] };
+}
+/** Persist the registry atomically. */
+export async function writeRegistry(reg) {
+    const dir = registryDir();
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, REGISTRY_FILE);
+    const tmp = file + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(reg, null, 2), 'utf-8');
+    await fs.rename(tmp, file);
+}
+/** Add or update a project entry. Identified by slug; if the
+ *  slug exists, merges fields (last_active_at + cached fields
+ *  win on update; path stays unless explicitly replaced). */
+export async function upsertProject(entry) {
+    const reg = await readRegistry();
+    const idx = reg.projects.findIndex((p) => p.slug === entry.slug);
+    const stamped = { ...entry, updated_at: entry.updated_at ?? new Date().toISOString() };
+    if (idx >= 0) {
+        reg.projects[idx] = { ...reg.projects[idx], ...stamped };
+    }
+    else {
+        reg.projects.push(stamped);
+    }
+    await writeRegistry(reg);
+    return reg;
+}
+/** Remove a project from the local registry. Does NOT delete
+ *  the repo on disk. */
+export async function removeProject(slug) {
+    const reg = await readRegistry();
+    reg.projects = reg.projects.filter((p) => p.slug !== slug);
+    if (reg.active_slug === slug)
+        reg.active_slug = null;
+    await writeRegistry(reg);
+    return reg;
+}
+/** Mark a project as active. Returns the new registry +
+ *  updates last_active_at on the targeted entry. */
+export async function setActive(slug) {
+    const reg = await readRegistry();
+    const entry = reg.projects.find((p) => p.slug === slug);
+    if (!entry)
+        throw new Error('project not in registry: ' + slug);
+    entry.last_active_at = new Date().toISOString();
+    reg.active_slug = slug;
+    await writeRegistry(reg);
+    return reg;
+}
+/** Get the slug of the currently-active project (or null). */
+export async function activeSlug() {
+    const reg = await readRegistry();
+    return reg.active_slug;
+}
+/** Look up a project entry by slug. */
+export async function getProject(slug) {
+    const reg = await readRegistry();
+    return reg.projects.find((p) => p.slug === slug);
+}
+/** Read the project's yujin.forge.json + derive a slug from
+ *  it (project.slug field, or fall back to the directory
+ *  basename). */
+export async function deriveSlugFromPath(projectPath) {
+    try {
+        const raw = await fs.readFile(path.join(projectPath, 'yujin.forge.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.slug === 'string' && parsed.slug.length > 0)
+            return parsed.slug;
+        if (typeof parsed.project_name === 'string') {
+            return slugify(parsed.project_name);
+        }
+    }
+    catch { /* not yet a Yujin project */ }
+    return slugify(path.basename(projectPath));
+}
+/** Scan a directory tree for `yujin.forge.json` files +
+ *  return their parent dirs. Skips node_modules, .git, dist.
+ *  Depth-limited to avoid pathological FS layouts. */
+export async function scanForProjects(scanRoot, maxDepth = 3) {
+    const out = [];
+    await walk(scanRoot, 0);
+    return out;
+    async function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist'
+                || e.name === '.yujin-forge' || e.name.startsWith('.'))
+                continue;
+            const abs = path.join(dir, e.name);
+            if (e.isFile() && e.name === 'yujin.forge.json') {
+                out.push(dir);
+            }
+            else if (e.isDirectory()) {
+                await walk(abs, depth + 1);
+            }
+        }
+    }
+}
+function slugify(s) {
+    return s.toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64) || 'unnamed';
+}
+//# sourceMappingURL=projects.js.map

package/dist/core/projects.js.map

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

package/dist/core/projects_sync.d.ts

@@ -0,0 +1,80 @@
+/**
+ * GitHub-anchored project sync (PLAN #10, soft #5).
+ *
+ * The user owns a private GitHub repo `yujin-state` whose
+ * `projects.json` file is the cross-device truth bus for their
+ * Forge project registry. This module:
+ *
+ *   - Bootstraps the repo + file on first sync (creates the
+ *     repo + commits an empty projects.json).
+ *   - Pulls the remote file via the GitHub Contents API.
+ *   - Merges per-slug into the local registry using
+ *     last-writer-wins on `updated_at`.
+ *   - Pushes the merged result back.
+ *
+ * Per-device fields (path, mode-on-this-device) are STRIPPED
+ * before push -- only the cross-device fields (slug,
+ * github_repo, target, mode-default, last_active_at,
+ * updated_at) ride.
+ *
+ * Auth: vault slot `github_token` with `repo` scope. Same slot
+ * used by `yf repo init` + the chat tools.
+ *
+ * Loud failures: missing vault slot, non-2xx API, optimistic
+ * concurrency conflict (412) -> retry once after re-pulling.
+ *
+ * ASCII-only.
+ */
+import { type ProjectEntry, type ProjectsRegistry } from './projects.js';
+declare const STATE_FILE_SCHEMA = "yujin-state/projects.json/v1";
+export interface SyncRemoteEntry {
+    slug: string;
+    github_repo?: string;
+    target?: string;
+    mode?: string;
+    last_active_at?: string;
+    updated_at: string;
+}
+export interface SyncRemoteState {
+    version: 1;
+    schema: typeof STATE_FILE_SCHEMA;
+    projects: SyncRemoteEntry[];
+}
+export interface SyncDeps {
+    fetchImpl?: typeof fetch;
+    /** Returns the PAT from the vault. */
+    tokenProvider: () => Promise<string>;
+    /** Returns the GitHub username (used to address the state repo). */
+    ownerProvider?: () => Promise<string>;
+    /** Override the state repo name (for tests). */
+    stateRepoName?: string;
+}
+export interface SyncResult {
+    ok: boolean;
+    remote_repo: string;
+    /** Slugs created on the local side as a result of the pull. */
+    pulled_new: string[];
+    /** Slugs updated on the local side (remote was newer). */
+    pulled_updated: string[];
+    /** Slugs pushed (local was newer or remote did not have them). */
+    pushed: string[];
+    /** True when the state repo had to be created on this run. */
+    bootstrapped: boolean;
+}
+export declare function toRemoteEntry(p: ProjectEntry): SyncRemoteEntry;
+/** Per-slug merge: keep the entry with the higher updated_at.
+ *  Returns [merged, classifications] -- classifications used
+ *  by SyncResult. */
+export declare function mergeRegistries(local: ProjectsRegistry, remote: SyncRemoteState): {
+    merged: ProjectsRegistry;
+    pulled_new: string[];
+    pulled_updated: string[];
+    pushed: string[];
+};
+/** Run a full bidirectional sync. Caller orchestrates retries. */
+export declare function syncProjects(opts: {
+    pullOnly?: boolean;
+    pushOnly?: boolean;
+} | undefined, deps: SyncDeps): Promise<SyncResult>;
+export {};
+//# sourceMappingURL=projects_sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projects_sync.d.ts","sourceRoot":"","sources":["../../src/core/projects_sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EACwB,KAAK,YAAY,EAAE,KAAK,gBAAgB,EACtE,MAAM,eAAe,CAAC;AAKvB,QAAA,MAAM,iBAAiB,iCAAiC,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,sCAAsC;IACtC,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAC;CACvB;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,GAAG,eAAe,CAS9D;AAED;;qBAEqB;AACrB,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,eAAe,GACtB;IACD,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA8DA;AAsHD,kEAAkE;AAClE,wBAAsB,YAAY,CAChC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,YAAK,EACrD,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,UAAU,CAAC,CA4DrB"}