youmd 0.6.21 → 0.6.27

package/dist/lib/stackUpdate.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * L17 — stack update channel.
+ *
+ * Checks the upstream registry for a newer version of a YouStack manifest.
+ * Falls back to the manifest's `update.source` field if no registry endpoint
+ * exists, querying the `repo` field in `owner` with `git ls-remote`.
+ *
+ * Contract:
+ *   - checkStackUpdate(loaded)  → StackUpdateInfo
+ *   - applyStackUpdate(loaded, info) → void (writes new files, does NOT commit)
+ */
+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.checkStackUpdate = checkStackUpdate;
+exports.applyStackUpdate = applyStackUpdate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+// ── Internal helpers ──────────────────────────────────────────────────────────
+/**
+ * Compare semver-ish version strings (e.g. "1.2.3"). Returns true when
+ * `upstream` is strictly newer than `local`. Non-semver strings fall back to
+ * a raw string comparison (!=).
+ */
+function isNewer(local, upstream) {
+    if (local === upstream)
+        return false;
+    const parse = (v) => v.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+    const a = parse(local);
+    const b = parse(upstream);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (bv > av)
+            return true;
+        if (bv < av)
+            return false;
+    }
+    return false;
+}
+/**
+ * Fetch the version from a remote youstack.json URL.
+ * Returns null on any fetch/parse error.
+ */
+async function fetchRemoteManifestVersion(url) {
+    try {
+        const resp = await fetch(url, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        return typeof data.version === "string" ? data.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch the first non-blank, non-heading line from a remote CHANGELOG.md URL.
+ * Returns null on any error.
+ */
+async function fetchChangelogHint(changelogUrl) {
+    try {
+        const resp = await fetch(changelogUrl, {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!resp.ok)
+            return null;
+        const text = await resp.text();
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed && !trimmed.startsWith("#"))
+                return trimmed.slice(0, 120);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the latest semver tag from a git remote URL using `git ls-remote`.
+ * Returns null when git is unavailable or the repo has no semver tags.
+ */
+function resolveLatestGitTag(repoUrl) {
+    try {
+        const output = (0, child_process_1.execFileSync)("git", ["ls-remote", "--tags", "--sort=-version:refname", repoUrl], { encoding: "utf8", timeout: 8000, stdio: ["ignore", "pipe", "ignore"] });
+        for (const line of output.split("\n")) {
+            const ref = line.split("\t")[1]?.trim();
+            if (!ref)
+                continue;
+            // Only plain tags, not peeled (^{}) refs. Strip refs/tags/ prefix.
+            if (ref.includes("^{}"))
+                continue;
+            const tag = ref.replace("refs/tags/", "");
+            if (/^\d/.test(tag) || /^v\d/.test(tag))
+                return tag.replace(/^v/, "");
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Main public function ──────────────────────────────────────────────────────
+/**
+ * Check whether the upstream source (registry endpoint → manifest source URL
+ * → git ls-remote on owner.repo) has a version newer than the local manifest.
+ */
+async function checkStackUpdate(loaded) {
+    const { manifest, rootDir } = loaded;
+    const currentVersion = manifest.version || "0.0.0";
+    // ── 1. registry endpoint (future: registry.you.md/stacks/<slug>) ──────────
+    // If the manifest has update.source pointing to a remote JSON URL, fetch it.
+    const sourceUrl = manifest.update?.source;
+    if (sourceUrl && sourceUrl.startsWith("http")) {
+        const latestVersion = await fetchRemoteManifestVersion(sourceUrl);
+        if (latestVersion) {
+            const updateAvailable = isNewer(currentVersion, latestVersion);
+            // Try a CHANGELOG.md beside the source manifest.
+            const changelogUrl = sourceUrl.replace(/youstack\.json$/, "CHANGELOG.md");
+            const changelogHint = await fetchChangelogHint(changelogUrl);
+            return {
+                currentVersion,
+                latestVersion,
+                updateAvailable,
+                source: "source-url",
+                changelogHint,
+                message: updateAvailable
+                    ? `update available: ${currentVersion} → ${latestVersion}`
+                    : `up to date (${currentVersion})`,
+            };
+        }
+    }
+    // ── 2. git ls-remote on owner.repo ───────────────────────────────────────
+    const ownerRecord = manifest.owner;
+    const repoField = typeof ownerRecord?.repo === "string" ? ownerRecord.repo : undefined;
+    if (repoField) {
+        // Resolve a full git remote URL. Bare "owner/name" → github https.
+        const gitUrl = repoField.startsWith("http")
+            ? repoField
+            : `https://github.com/${repoField}.git`;
+        const latestVersion = resolveLatestGitTag(gitUrl);
+        if (latestVersion) {
+            const updateAvailable = isNewer(currentVersion, latestVersion);
+            // Check for a local CHANGELOG.md beside the manifest as a hint.
+            let changelogHint = null;
+            const localChangelog = path.join(rootDir, "CHANGELOG.md");
+            if (fs.existsSync(localChangelog)) {
+                const content = fs.readFileSync(localChangelog, "utf8");
+                for (const line of content.split("\n")) {
+                    const t = line.trim();
+                    if (t && !t.startsWith("#")) {
+                        changelogHint = t.slice(0, 120);
+                        break;
+                    }
+                }
+            }
+            return {
+                currentVersion,
+                latestVersion,
+                updateAvailable,
+                source: "git-ls-remote",
+                changelogHint,
+                message: updateAvailable
+                    ? `update available: ${currentVersion} → ${latestVersion}`
+                    : `up to date (${currentVersion})`,
+            };
+        }
+    }
+    // ── 3. nothing found ─────────────────────────────────────────────────────
+    return {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: false,
+        source: "none",
+        changelogHint: null,
+        message: "no upstream version source configured (set update.source or owner.repo)",
+    };
+}
+/**
+ * Apply an update by fetching the manifest from update.source and writing it
+ * into place.  Only available when source is "source-url".
+ *
+ * Does NOT commit or push. Writes the new youstack.json at manifestPath.
+ */
+async function applyStackUpdate(loaded) {
+    const { manifest, manifestPath } = loaded;
+    const sourceUrl = manifest.update?.source;
+    if (!sourceUrl || !sourceUrl.startsWith("http")) {
+        return {
+            wrote: [],
+            skipped: [],
+            error: "apply requires update.source to be an http(s) URL in the manifest",
+        };
+    }
+    try {
+        const resp = await fetch(sourceUrl, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!resp.ok) {
+            return {
+                wrote: [],
+                skipped: [],
+                error: `fetch failed: ${resp.status} ${resp.statusText}`,
+            };
+        }
+        const newManifest = await resp.text();
+        fs.writeFileSync(manifestPath, newManifest, "utf8");
+        return { wrote: [manifestPath], skipped: [], error: null };
+    }
+    catch (err) {
+        return {
+            wrote: [],
+            skipped: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=stackUpdate.js.map

package/dist/lib/stackUpdate.js.map

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

package/dist/lib/stream.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Streaming display utilities (U6 + U16).
+ *
+ * The You Agent embeds machine-directives in its responses as ```json fenced
+ * blocks (profile updates, memory saves, private updates, project updates).
+ * The full-text parsers in chat.ts / onboarding.ts consume those blocks AFTER
+ * the stream completes — but during live streaming the raw blocks used to be
+ * written straight to the terminal.
+ *
+ * This module provides:
+ *   1. JsonDirectiveStreamFilter — a pure, incremental transformer that
+ *      suppresses ```json directive blocks from DISPLAYED output while the
+ *      caller keeps accumulating the raw text for the post-stream parsers.
+ *   2. createFilteredStdoutWriter — terminal writer that applies the filter
+ *      and shows a dim placeholder when a directive block is being swallowed
+ *      and nothing visible has been written yet.
+ *   3. streamSSEText — shared SSE reader for /api/v1/chat/stream.
+ *   4. streamAssistantTurn — the shared spinner + stream + filter + fallback
+ *      helper used by both `youmd chat` and onboarding turns 2+.
+ *
+ * NOTE: the transformer is mirrored (separate npm package boundaries) in
+ * src/hooks/stream-filter.ts for the web You Agent. A parity test in
+ * cli/src/__tests__/stream-filter.test.ts asserts the two never drift.
+ */
+export declare const DIRECTIVE_SWALLOW_PLACEHOLDER = "(updating your profile\u2026)";
+/**
+ * Incremental transformer: feed(chunk) → displayable text.
+ *
+ * - Holds back a partial backtick run / undetermined fence opener at the end
+ *   of the buffer until disambiguated (fences split across chunk boundaries).
+ * - Once inside a ```json fence, swallows everything until the closing fence,
+ *   plus the whitespace run immediately after it (so no blank gap remains).
+ * - Non-json fences (``` alone or any other language) pass through unchanged.
+ * - flush() releases any held-back non-directive text at end of stream.
+ */
+export declare class JsonDirectiveStreamFilter {
+    private state;
+    /** Pending backtick run at the end of the buffer (text state). */
+    private tickRun;
+    /** Held "```<info>" while determining the fence language. */
+    private fenceBuf;
+    /** Match progress for the "\n```" closing fence (json/code states). */
+    private closeProgress;
+    private blocks;
+    private visible;
+    private swallowedEver;
+    /** Feed a raw chunk; returns the displayable portion (may be empty). */
+    feed(chunk: string): string;
+    /** End of stream: release held-back non-directive text. */
+    flush(): string;
+    /** Currently inside a ```json directive block (actively swallowing). */
+    get isSwallowing(): boolean;
+    /** At least one ```json directive block was encountered. */
+    get hasSwallowedDirective(): boolean;
+    /** Some non-whitespace text has been emitted for display. */
+    get hasVisibleOutput(): boolean;
+    /** Number of ```json directive blocks encountered so far. */
+    get directiveBlockCount(): number;
+}
+export interface FilteredStreamWriter {
+    /** Feed a raw streamed token; writes only the displayable portion. */
+    write(token: string): void;
+    /** Flush held text and terminate the streamed line(s). */
+    finish(): void;
+    /** Whether any displayable text was written to the terminal. */
+    readonly wroteVisible: boolean;
+}
+interface MinimalWritable {
+    write(text: string): unknown;
+}
+/**
+ * Wrap stdout with the directive filter. Shows a subtle dim placeholder when
+ * a ```json block is being swallowed and the response would otherwise look
+ * empty mid-stream; clears it the moment real text arrives.
+ */
+export declare function createFilteredStdoutWriter(opts?: {
+    out?: MinimalWritable;
+    indent?: string;
+    placeholder?: string;
+}): FilteredStreamWriter;
+export interface ChatTurnMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * Stream a chat response token-by-token from a you.md SSE endpoint.
+ * Calls onToken with each RAW text delta (unfiltered — display filtering is
+ * the caller's concern) and returns the full assembled raw response.
+ */
+export declare function streamSSEText(streamUrl: string, messages: ChatTurnMessage[], onToken: (text: string) => void, timeoutMs?: number): Promise<string>;
+export interface StreamAssistantTurnOptions {
+    streamUrl: string;
+    messages: ChatTurnMessage[];
+    /** BrailleSpinner label shown while waiting for the first token. */
+    spinnerLabel: string;
+    timeoutMs?: number;
+    /** Blocking fallback (e.g. callLLM) used when streaming fails or is empty. */
+    fallback?: () => Promise<string>;
+    placeholder?: string;
+}
+/**
+ * Run one assistant turn: spinner while waiting for the first token, then
+ * live-stream the response with ```json directive blocks filtered out of the
+ * display. Returns the FULL RAW response text (directives intact) so the
+ * existing post-stream parsers keep working, plus whether it streamed.
+ *
+ * On stream failure (or an empty stream) falls back to the provided blocking
+ * call; in that case `streamed` is false and the caller is expected to render
+ * the parsed display text itself.
+ */
+export declare function streamAssistantTurn(opts: StreamAssistantTurnOptions): Promise<{
+    text: string;
+    streamed: boolean;
+}>;
+export {};
+//# sourceMappingURL=stream.d.ts.map

package/dist/lib/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/lib/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAcH,eAAO,MAAM,6BAA6B,kCAA6B,CAAC;AAExE;;;;;;;;;GASG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,KAAK,CAAuB;IACpC,kEAAkE;IAClE,OAAO,CAAC,OAAO,CAAK;IACpB,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAM;IACtB,uEAAuE;IACvE,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAE9B,wEAAwE;IACxE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IA2G3B,2DAA2D;IAC3D,KAAK,IAAI,MAAM;IAkBf,wEAAwE;IACxE,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,4DAA4D;IAC5D,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAED,6DAA6D;IAC7D,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAED,6DAA6D;IAC7D,IAAI,mBAAmB,IAAI,MAAM,CAEhC;CACF;AAID,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,MAAM,IAAI,IAAI,CAAC;IACf,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,UAAU,eAAe;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1E,oBAAoB,CAyCtB;AAID,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,eAAe,EAAE,EAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,SAAU,GAClB,OAAO,CAAC,MAAM,CAAC,CAiDjB;AAID,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAwD9C"}