@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/services/Skill.js

@@ -0,0 +1,421 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { FileSystem, Path } from '@effect/platform';
+import { Context, Effect, Layer, Ref } from 'effect';
+import MiniSearch from 'minisearch';
+import { ChapterNotFound, SkillCorpusEmpty } from '../domain/errors';
+const requireFrom = createRequire(import.meta.url);
+const findCliPackageRoot = () => {
+    const here = fileURLToPath(import.meta.url);
+    let dir = here.slice(0, Math.max(0, here.lastIndexOf('/')));
+    for (let i = 0; i < 8; i++) {
+        if (!dir || dir === '/')
+            break;
+        try {
+            const pkg = requireFrom(`${dir}/package.json`);
+            if (pkg.name === '@mx-space/cli')
+                return dir;
+        }
+        catch {
+            // not a pkg dir, keep walking
+        }
+        const next = dir.slice(0, Math.max(0, dir.lastIndexOf('/')));
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    return null;
+};
+const resolveCliSkillsDir = () => {
+    const override = process.env.MXS_SKILL_CLI_DIR;
+    if (override && override.length > 0)
+        return override;
+    const root = findCliPackageRoot();
+    return root ? `${root}/skills` : null;
+};
+const resolveHaklexSkillsDir = () => {
+    const override = process.env.MXS_SKILL_HAKLEX_DIR;
+    if (override && override.length > 0)
+        return override;
+    try {
+        const pkgJson = requireFrom.resolve('@haklex/rich-litexml/package.json');
+        const dir = pkgJson.slice(0, Math.max(0, pkgJson.lastIndexOf('/')));
+        return `${dir}/.claude/skills/litexml-authoring`;
+    }
+    catch {
+        // Older `@haklex/rich-litexml` (<= 0.15.2) omits `./package.json` from
+        // its `exports`, so direct resolve throws under strict ESM resolution.
+        // Fall back to walking node_modules upward from the cli package root.
+        const root = findCliPackageRoot();
+        if (!root)
+            return null;
+        const candidates = [];
+        let dir = root;
+        while (dir && dir.length > 1) {
+            candidates.push(`${dir}/node_modules/@haklex/rich-litexml/.claude/skills/litexml-authoring`);
+            const next = dir.slice(0, Math.max(0, dir.lastIndexOf('/')));
+            if (next === dir)
+                break;
+            dir = next;
+        }
+        for (const c of candidates) {
+            if (existsSync(c))
+                return c;
+        }
+        return null;
+    }
+};
+const parseFrontmatter = (raw, file) => {
+    if (!raw.startsWith('---\n')) {
+        return { error: `${file}: missing frontmatter (no leading '---' line)` };
+    }
+    const end = raw.indexOf('\n---\n', 4);
+    if (end < 0) {
+        return { error: `${file}: missing frontmatter terminator ('---' line)` };
+    }
+    const head = raw.slice(4, end);
+    const body = raw.slice(end + 5).replace(/^\n+/, '');
+    const fields = {};
+    for (const line of head.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        const colon = line.indexOf(':');
+        if (colon < 0) {
+            return { error: `${file}: malformed frontmatter line: ${line}` };
+        }
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        fields[key] = value;
+    }
+    const slug = fields.slug;
+    const title = fields.title;
+    const description = fields.description;
+    const orderRaw = fields.order;
+    if (!slug)
+        return { error: `${file}: frontmatter missing required 'slug'` };
+    if (!title)
+        return { error: `${file}: frontmatter missing required 'title'` };
+    if (!description)
+        return { error: `${file}: frontmatter missing required 'description'` };
+    if (!orderRaw)
+        return { error: `${file}: frontmatter missing required 'order'` };
+    const order = Number.parseInt(orderRaw, 10);
+    if (!Number.isFinite(order)) {
+        return { error: `${file}: frontmatter 'order' not an integer: ${orderRaw}` };
+    }
+    if (!/^[\da-z][\da-z-]*$/.test(slug)) {
+        return { error: `${file}: frontmatter 'slug' not kebab-case: ${slug}` };
+    }
+    return { slug, title, description, order, body };
+};
+const scanCliDir = (fs, path, dir) => Effect.gen(function* () {
+    const exists = yield* fs
+        .exists(dir)
+        .pipe(Effect.catchAll(() => Effect.succeed(false)));
+    if (!exists)
+        return [];
+    const entries = yield* fs
+        .readDirectory(dir)
+        .pipe(Effect.catchAll(() => Effect.succeed([])));
+    const chapters = [];
+    for (const name of entries) {
+        if (!name.endsWith('.md'))
+            continue;
+        const full = path.join(dir, name);
+        const raw = yield* fs
+            .readFileString(full)
+            .pipe(Effect.catchAll(() => Effect.succeed('')));
+        if (!raw)
+            continue;
+        const parsed = parseFrontmatter(raw, full);
+        if ('error' in parsed) {
+            return yield* Effect.die(parsed.error);
+        }
+        chapters.push({ ...parsed, source: 'cli' });
+    }
+    return chapters;
+});
+const stripAnyFrontmatter = (raw) => {
+    if (!raw.startsWith('---\n')) {
+        return { fields: {}, body: raw };
+    }
+    const end = raw.indexOf('\n---\n', 4);
+    if (end < 0)
+        return { fields: {}, body: raw };
+    const head = raw.slice(4, end);
+    const body = raw.slice(end + 5).replace(/^\n+/, '');
+    const fields = {};
+    for (const line of head.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        const colon = line.indexOf(':');
+        if (colon < 0)
+            continue;
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        fields[key] = value;
+    }
+    return { fields, body };
+};
+const humanizeBase = (name) => name.replaceAll(/[_-]+/g, ' ').replaceAll(/\b\w/g, (c) => c.toUpperCase());
+const firstNonEmptyLine = (body) => {
+    for (const line of body.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        return trimmed.slice(0, 200);
+    }
+    return null;
+};
+const scanHaklexDir = (fs, path, dir) => Effect.gen(function* () {
+    const exists = yield* fs
+        .exists(dir)
+        .pipe(Effect.catchAll(() => Effect.succeed(false)));
+    if (!exists)
+        return [];
+    const chapters = [];
+    const skillMdPath = path.join(dir, 'SKILL.md');
+    const skillMdExists = yield* fs
+        .exists(skillMdPath)
+        .pipe(Effect.catchAll(() => Effect.succeed(false)));
+    if (skillMdExists) {
+        const raw = yield* fs
+            .readFileString(skillMdPath)
+            .pipe(Effect.catchAll(() => Effect.succeed('')));
+        if (raw) {
+            const { fields, body } = stripAnyFrontmatter(raw);
+            chapters.push({
+                slug: 'litexml',
+                title: 'liteXML overview',
+                description: fields.description ||
+                    firstNonEmptyLine(body) ||
+                    'liteXML node and authoring reference',
+                order: 70,
+                source: 'haklex',
+                body,
+            });
+        }
+    }
+    const refsDir = path.join(dir, 'references');
+    const refsExists = yield* fs
+        .exists(refsDir)
+        .pipe(Effect.catchAll(() => Effect.succeed(false)));
+    if (refsExists) {
+        const refFiles = yield* fs
+            .readDirectory(refsDir)
+            .pipe(Effect.catchAll(() => Effect.succeed([])));
+        const sorted = [...refFiles].filter((n) => n.endsWith('.md')).sort();
+        let order = 71;
+        for (const name of sorted) {
+            const full = path.join(refsDir, name);
+            const raw = yield* fs
+                .readFileString(full)
+                .pipe(Effect.catchAll(() => Effect.succeed('')));
+            if (!raw)
+                continue;
+            const baseName = name.replace(/\.md$/, '');
+            const { fields, body } = stripAnyFrontmatter(raw);
+            chapters.push({
+                slug: `litexml-${baseName}`,
+                title: `liteXML ${humanizeBase(baseName)}`,
+                description: fields.description ||
+                    firstNonEmptyLine(body) ||
+                    `liteXML reference: ${baseName}`,
+                order: order++,
+                source: 'haklex',
+                body,
+            });
+        }
+    }
+    return chapters;
+});
+const buildRegistry = (fs, path, cliDir, haklexDir) => Effect.gen(function* () {
+    const [cliChapters, haklexChapters] = yield* Effect.all([
+        cliDir
+            ? scanCliDir(fs, path, cliDir)
+            : Effect.succeed([]),
+        haklexDir
+            ? scanHaklexDir(fs, path, haklexDir)
+            : Effect.succeed([]),
+    ], { concurrency: 2 }).pipe(Effect.catchAllDefect((d) => Effect.fail(new SkillCorpusEmpty({
+        message: typeof d === 'string' ? d : 'failed to load skill corpus',
+        cause: d,
+    }))));
+    const all = [...cliChapters, ...haklexChapters];
+    if (all.length === 0) {
+        return yield* Effect.fail(new SkillCorpusEmpty({
+            message: 'no chapters found',
+            hint: 'reinstall @mx-space/cli, or check the MXS_SKILL_CLI_DIR / MXS_SKILL_HAKLEX_DIR overrides',
+        }));
+    }
+    const seen = new Set();
+    for (const c of all) {
+        if (seen.has(c.slug)) {
+            return yield* Effect.fail(new SkillCorpusEmpty({
+                message: `duplicate slug across sources: ${c.slug}`,
+                hint: 'each chapter slug must be globally unique',
+            }));
+        }
+        seen.add(c.slug);
+    }
+    return [...all].sort((a, b) => a.order - b.order);
+});
+const buildIndex = (chapters) => {
+    const mini = new MiniSearch({
+        fields: ['title', 'description', 'body'],
+        storeFields: ['slug'],
+        idField: 'slug',
+        searchOptions: {
+            boost: { title: 3, description: 2 },
+            combineWith: 'AND',
+            prefix: true,
+            fuzzy: 0.2,
+        },
+    });
+    mini.addAll(chapters.map((c) => ({
+        slug: c.slug,
+        title: c.title,
+        description: c.description,
+        body: c.body,
+    })));
+    return mini;
+};
+/**
+ * Tokenize the user's query string the same way MiniSearch does for indexing,
+ * so snippets can be located in the body. We use this lightweight tokenizer
+ * rather than `r.terms` because fuzzy / prefix matches expose the indexed
+ * term, not the substring that appears in the body verbatim.
+ */
+const tokenizeQuery = (s) => s
+    .toLowerCase()
+    .split(/[\s\p{P}]+/u)
+    .filter((t) => t.length > 0);
+const buildSnippets = (body, terms) => {
+    if (terms.length === 0)
+        return [];
+    const lower = body.toLowerCase();
+    // Pre-collect up to 5 occurrences per term so single-term queries can
+    // surface multiple snippets and multi-term queries stay balanced via
+    // round-robin emission below.
+    const occs = terms.map((term) => {
+        const t = term.toLowerCase();
+        if (!t)
+            return [];
+        const positions = [];
+        let from = 0;
+        while (positions.length < 5) {
+            const idx = lower.indexOf(t, from);
+            if (idx < 0)
+                break;
+            positions.push(idx);
+            from = idx + t.length;
+        }
+        return positions;
+    });
+    const cursors = Array.from({ length: terms.length }, () => 0);
+    const out = [];
+    let progressed = true;
+    while (out.length < 3 && progressed) {
+        progressed = false;
+        for (let i = 0; i < terms.length && out.length < 3; i++) {
+            const c = cursors[i];
+            if (c >= occs[i].length)
+                continue;
+            const idx = occs[i][c];
+            const tLen = terms[i].length;
+            cursors[i] = c + 1;
+            progressed = true;
+            const start = Math.max(0, idx - 60);
+            const end = Math.min(body.length, idx + tLen + 60);
+            let snippet = body.slice(start, end).replaceAll(/\s+/g, ' ').trim();
+            if (start > 0)
+                snippet = `…${snippet}`;
+            if (end < body.length)
+                snippet = `${snippet}…`;
+            out.push(snippet);
+        }
+    }
+    return out;
+};
+const make = Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const cliDir = resolveCliSkillsDir();
+    const haklexDir = resolveHaklexSkillsDir();
+    const cache = yield* Ref.make(null);
+    const indexCache = yield* Ref.make(null);
+    const load = Effect.gen(function* () {
+        const cached = yield* Ref.get(cache);
+        if (cached)
+            return cached;
+        const chapters = yield* buildRegistry(fs, path, cliDir, haklexDir);
+        yield* Ref.set(cache, chapters);
+        return chapters;
+    });
+    const loadIndex = Effect.gen(function* () {
+        const cached = yield* Ref.get(indexCache);
+        if (cached)
+            return cached;
+        const chapters = yield* load;
+        const mini = buildIndex(chapters);
+        yield* Ref.set(indexCache, mini);
+        return mini;
+    });
+    const svc = {
+        list: load,
+        all: load,
+        get: (slug) => Effect.gen(function* () {
+            const chapters = yield* load;
+            const found = chapters.find((c) => c.slug === slug);
+            if (!found) {
+                const isLitexml = slug.startsWith('litexml');
+                return yield* Effect.fail(new ChapterNotFound({
+                    slug,
+                    message: `no skill chapter with slug '${slug}'`,
+                    hint: isLitexml
+                        ? 'upgrade @haklex/rich-litexml to >=0.36.1 to ship liteXML chapters'
+                        : 'run `mxs skill` to list available chapters',
+                }));
+            }
+            return found;
+        }),
+        search: (keyword) => Effect.gen(function* () {
+            const kw = keyword.trim();
+            if (!kw)
+                return [];
+            const chapters = yield* load;
+            const mini = yield* loadIndex;
+            const tokens = tokenizeQuery(kw);
+            const results = mini.search(kw);
+            const bySlug = new Map(chapters.map((c) => [c.slug, c]));
+            return results.flatMap((r) => {
+                const chapter = bySlug.get(r.id);
+                if (!chapter)
+                    return [];
+                return [
+                    {
+                        slug: chapter.slug,
+                        title: chapter.title,
+                        description: chapter.description,
+                        snippets: buildSnippets(chapter.body, tokens),
+                    },
+                ];
+            });
+        }),
+    };
+    return svc;
+});
+export class Skill extends Context.Tag('Skill')() {
+    static Default = Layer.effect(Skill, make);
+}

package/dist/src/services/UpdateNotifier.d.ts

@@ -0,0 +1,162 @@
+import { Context, Effect, Layer } from 'effect';
+import { type Generic, UpdateDevEnvironment, UpdateNodeIncompatible, UpdatePermissionDenied, UpdatePmUnknown, UpdateRegistryUnreachable, UpdateSpawnFailed, UpdateTransientInstall } from '../domain/errors';
+export type UpdateChannel = 'stable' | 'next';
+export type PmKind = 'npm' | 'pnpm' | 'yarn' | 'bun';
+export declare const PACKAGE_NAME = "@mx-space/cli";
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export interface NotifyOptions {
+    readonly currentVersion: string;
+    readonly channel?: UpdateChannel;
+    readonly quiet?: boolean;
+    readonly json?: boolean;
+    readonly output?: string;
+    readonly commandName?: string;
+    readonly parentName?: string;
+    readonly force?: boolean;
+    readonly isTTY?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly emit?: (message: string) => void;
+    readonly configDir?: string;
+}
+export interface RunUpdateOptions {
+    readonly currentVersion: string;
+    readonly channel?: UpdateChannel;
+    readonly dryRun?: boolean;
+    readonly check?: boolean;
+    readonly prerelease?: boolean;
+    readonly pm?: string;
+    readonly yes?: boolean;
+    readonly force?: boolean;
+    readonly json?: boolean;
+    /** Override `process.argv[1]` for pm detection (tests). */
+    readonly entrypoint?: string;
+    /** Override Node version for engine compatibility check (tests). */
+    readonly nodeVersion?: string;
+}
+export interface RunUpdateResult {
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly pm: PmKind | null;
+    readonly channel: UpdateChannel;
+    readonly status: number;
+    /** true when the package manager actually ran and succeeded. */
+    readonly upgraded: boolean;
+    /** true when no install was performed (already up to date / --check / --dry-run / cancelled). */
+    readonly dryRun: boolean;
+    /** true when local version >= registry latest. */
+    readonly upToDate: boolean;
+    readonly command?: string;
+    readonly cancelled?: boolean;
+}
+export type RunUpdateError = UpdateDevEnvironment | UpdateTransientInstall | UpdatePmUnknown | UpdateRegistryUnreachable | UpdateNodeIncompatible | UpdateSpawnFailed | UpdatePermissionDenied | Generic;
+export interface UpdateNotifierService {
+    readonly maybeNotify: (opts: NotifyOptions) => Effect.Effect<void>;
+    readonly runUpdate: (opts: RunUpdateOptions) => Effect.Effect<RunUpdateResult, RunUpdateError>;
+}
+export type PmDetection = {
+    kind: 'global';
+    pm: PmKind;
+    realPath: string;
+} | {
+    kind: 'dev';
+    reason: 'monorepo-source' | 'monorepo-dist';
+    realPath: string;
+} | {
+    kind: 'transient';
+    cache: 'npx' | 'pnpm-dlx' | 'bunx';
+    realPath: string;
+} | {
+    kind: 'unknown';
+    realPath: string;
+};
+export declare function detectPackageManager(argv1: string): PmDetection;
+export interface RegistryHit {
+    notModified?: false;
+    version: string;
+    engines?: {
+        node?: string;
+    };
+    tarball?: string;
+    etag?: string;
+}
+export interface NotModified {
+    notModified: true;
+    etag?: string;
+}
+export type FetchImpl = (input: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get: (name: string) => string | null;
+    };
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+export interface FetchOpts {
+    etag?: string;
+    signal?: AbortSignal;
+    registry?: string;
+    fetchImpl?: FetchImpl;
+}
+export declare function fetchLatestVersion(channel: UpdateChannel, opts?: FetchOpts): Promise<RegistryHit | NotModified>;
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+export declare function satisfiesNodeEngine(currentVersion: string, range: string | undefined): boolean;
+export declare function buildUpgradeCommand(pm: PmKind, channel: UpdateChannel): {
+    cmd: string;
+    args: string[];
+};
+export interface SpawnUpgradeResult {
+    status: number;
+    stderr: string;
+}
+export type SpawnDetached = (cmd: string, args: string[], logPath: string) => void;
+export interface CachedState {
+    last_check_ts: number;
+    latest_version?: string;
+    etag?: string;
+    /**
+     * Timestamp of the most recent background auto-update spawn. Used to throttle
+     * silent installs so a single new release doesn't trigger an `npm i -g` on
+     * every `mxs <cmd>` invocation within the 24h check window.
+     */
+    last_auto_update_ts?: number;
+}
+export declare function readCache(configDir: string): CachedState | null;
+export declare function writeCacheAtomic(state: CachedState, configDir: string): void;
+export declare function shouldSkipNotify(opts: NotifyOptions): boolean;
+export interface UpdateNotifierDeps {
+    readonly now?: () => number;
+    readonly fetchImpl?: FetchImpl;
+    readonly spawnImpl?: (cmd: string, args: string[]) => Promise<SpawnUpgradeResult>;
+    /**
+     * Fire-and-forget detached spawn used by the background auto-update path.
+     * Unit tests can inject a spy to verify that an install was triggered
+     * without actually running the package manager.
+     */
+    readonly spawnDetached?: SpawnDetached;
+    /**
+     * @deprecated The interactive confirm prompt was removed when `mxs update`
+     * became auto-install by default. Accepted for backward compatibility with
+     * older `make()` call sites; never invoked.
+     */
+    readonly confirmImpl?: (message: string) => Promise<boolean>;
+    readonly emitInfo?: (msg: string) => void;
+    readonly configDir?: string;
+    /**
+     * Override `process.argv[1]` for the background auto-update path's pm
+     * detection. Production callers leave this unset and the helper reads
+     * argv directly.
+     */
+    readonly entrypoint?: string;
+}
+export declare const make: (deps?: UpdateNotifierDeps) => UpdateNotifierService;
+declare const UpdateNotifier_base: Context.TagClass<UpdateNotifier, "UpdateNotifier", UpdateNotifierService>;
+export declare class UpdateNotifier extends UpdateNotifier_base {
+    static Default: Layer.Layer<UpdateNotifier>;
+}
+/** Build a custom UpdateNotifier layer (tests). */
+export declare const layer: (deps?: UpdateNotifierDeps) => Layer.Layer<UpdateNotifier>;
+export {};