@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/services/Resolver.js

@@ -0,0 +1,269 @@
+import { Context, Effect, Layer } from 'effect';
+import { Generic, ResourceNotFound, ValidationFailed } from '../domain/errors';
+import { Api } from './Api';
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+const SNOWFLAKE_RE = /^\d{15,}$/;
+export const isSnowflakeId = (value) => SNOWFLAKE_RE.test(value);
+export function matchItem(items, value) {
+    const bySlug = items.find((i) => i.slug && i.slug === value);
+    if (bySlug)
+        return bySlug;
+    const byName = items.find((i) => i.name && i.name === value);
+    if (byName)
+        return byName;
+    const lower = value.toLowerCase();
+    const byNameCi = items.find((i) => i.name && i.name.toLowerCase() === lower);
+    if (byNameCi)
+        return byNameCi;
+    const bySlugCi = items.find((i) => i.slug && i.slug.toLowerCase() === lower);
+    if (bySlugCi)
+        return bySlugCi;
+    return null;
+}
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    let prev = Array.from({ length: n + 1 });
+    let curr = Array.from({ length: n + 1 });
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min((curr[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        ;
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n] ?? 0;
+}
+export function fuzzySuggest(items, value, maxDistance = 2) {
+    const lower = value.toLowerCase();
+    const scored = [];
+    for (const item of items) {
+        const candidates = [];
+        if (item.name)
+            candidates.push(item.name);
+        if (item.slug)
+            candidates.push(item.slug);
+        let best = Number.POSITIVE_INFINITY;
+        let label = item.name ?? item.slug ?? item.id;
+        for (const c of candidates) {
+            const d = levenshtein(c.toLowerCase(), lower);
+            if (d < best) {
+                best = d;
+                label = c;
+            }
+        }
+        if (best <= maxDistance)
+            scored.push({ label, score: best });
+    }
+    scored.sort((a, b) => a.score - b.score);
+    return scored.slice(0, 3).map((s) => s.label);
+}
+// ---------------------------------------------------------------------------
+// Service factory
+// ---------------------------------------------------------------------------
+const DEFAULT_TTL_MS = 60_000;
+const unwrapArrayEnvelope = (raw) => {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === 'object') {
+        const inner = raw.data;
+        if (Array.isArray(inner))
+            return inner;
+    }
+    return [];
+};
+const mapApiError = (err) => {
+    // Network/Auth/Server errors are surfaced as Generic; Validation passes through.
+    if (err._tag === 'ValidationFailed')
+        return err;
+    // Wrap everything else as Generic to satisfy the narrowed return channel.
+    // (We intentionally do NOT swallow — caller still sees a typed error.)
+    return new Generic({
+        message: err.message ?? 'resolver: api request failed',
+        details: err.details,
+        hint: err.hint,
+    });
+};
+export const make = (api, deps = {}) => {
+    const cache = new Map();
+    const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS;
+    const URLS_BY_KIND = {
+        category: '/categories',
+        topic: '/topics/all',
+        project: '/projects/all',
+    };
+    const load = (kind) => Effect.gen(function* () {
+        const cached = cache.get(kind);
+        const t = Date.now();
+        if (cached && cached.expiresAt > t)
+            return cached.items;
+        const raw = yield* api
+            .raw(URLS_BY_KIND[kind])
+            .pipe(Effect.mapError(mapApiError));
+        const items = unwrapArrayEnvelope(raw);
+        cache.set(kind, { items, expiresAt: t + ttlMs });
+        return items;
+    });
+    const resolveWith = (kind, value) => Effect.gen(function* () {
+        if (isSnowflakeId(value))
+            return value;
+        const items = yield* load(kind);
+        const hit = matchItem(items, value);
+        if (hit)
+            return hit.id;
+        const suggestions = fuzzySuggest(items, value);
+        return yield* Effect.fail(new ValidationFailed({
+            message: `${kind} "${value}" not found`,
+            details: {
+                issues: [
+                    {
+                        path: ['meta', kind],
+                        message: 'not found',
+                        ...(suggestions.length ? { suggestions } : {}),
+                    },
+                ],
+            },
+            hint: kind === 'category'
+                ? 'run `mxs category list` to see available categories'
+                : 'run `mxs topic list` to see available topics',
+        }));
+    });
+    const resolveCategory = (value) => resolveWith('category', value);
+    const resolveTopic = (value) => resolveWith('topic', value);
+    const resolveCategoryRefs = (refs) => Effect.forEach(refs, (ref) => resolveCategory(ref), { concurrency: 1 });
+    // -- Post / Note / Category direct API resolvers (port of commands/*/resolve.ts)
+    const resolvePostReadPath = (slugOrId) => Effect.gen(function* () {
+        if (isSnowflakeId(slugOrId))
+            return `/posts/${slugOrId}`;
+        const raw = yield* api
+            .raw(`/posts/get-url/${encodeURIComponent(slugOrId)}`)
+            .pipe(Effect.mapError(mapApiError));
+        const env = raw;
+        const path = env?.data?.path ?? env?.path;
+        if (!path) {
+            return yield* Effect.fail(new ResourceNotFound({
+                message: `post not found: ${slugOrId}`,
+                kind: 'post',
+                ref: slugOrId,
+            }));
+        }
+        return `/posts${path.startsWith('/') ? path : `/${path}`}`;
+    });
+    const resolvePostId = (slugOrId) => Effect.gen(function* () {
+        if (isSnowflakeId(slugOrId))
+            return slugOrId;
+        const apiPath = yield* resolvePostReadPath(slugOrId);
+        const raw = yield* api.raw(apiPath).pipe(Effect.mapError(mapApiError));
+        const env = raw;
+        const id = env?.data?.id ?? env?.id;
+        if (!id) {
+            return yield* Effect.fail(new ResourceNotFound({
+                message: `post not found: ${slugOrId}`,
+                kind: 'post',
+                ref: slugOrId,
+            }));
+        }
+        return id;
+    });
+    const resolveNoteId = (slugOrId) => Effect.gen(function* () {
+        if (isSnowflakeId(slugOrId))
+            return slugOrId;
+        if (/^\d+$/.test(slugOrId)) {
+            const raw = yield* api
+                .raw(`/notes/nid/${encodeURIComponent(slugOrId)}`, {
+                query: { single: '1' },
+            })
+                .pipe(Effect.mapError(mapApiError));
+            const env = raw;
+            const id = env?.data?.id ?? env?.id;
+            if (!id) {
+                return yield* Effect.fail(new ResourceNotFound({
+                    message: `note not found: ${slugOrId}`,
+                    kind: 'note',
+                    ref: slugOrId,
+                }));
+            }
+            return id;
+        }
+        return yield* Effect.fail(new ValidationFailed({
+            message: `invalid note reference: ${slugOrId} (use snowflake id or numeric nid)`,
+        }));
+    });
+    const resolveCategoryId = (slugOrId) => Effect.gen(function* () {
+        if (isSnowflakeId(slugOrId))
+            return slugOrId;
+        const raw = yield* api
+            .raw(`/categories/${encodeURIComponent(slugOrId)}`)
+            .pipe(Effect.mapError(mapApiError));
+        const id = raw?.data?.id;
+        if (!id) {
+            return yield* Effect.fail(new ResourceNotFound({
+                message: `category not found: ${slugOrId}`,
+                kind: 'category',
+                ref: slugOrId,
+            }));
+        }
+        return id;
+    });
+    const resolveProjectId = (nameOrId) => Effect.gen(function* () {
+        if (isSnowflakeId(nameOrId))
+            return nameOrId;
+        const items = yield* load('project');
+        const hit = matchItem(items, nameOrId);
+        if (hit)
+            return hit.id;
+        const suggestions = fuzzySuggest(items, nameOrId);
+        return yield* Effect.fail(new ResourceNotFound({
+            message: `project not found: ${nameOrId}`,
+            kind: 'project',
+            ref: nameOrId,
+            ...(suggestions.length ? { details: { suggestions } } : {}),
+            hint: 'run `mxs project list` to see available projects',
+        }));
+    });
+    const invalidate = (kind) => Effect.sync(() => {
+        if (!kind) {
+            cache.clear();
+            return;
+        }
+        cache.delete(kind);
+    });
+    return {
+        resolveCategory,
+        resolveTopic,
+        resolveCategoryRefs,
+        resolvePostId,
+        resolvePostReadPath,
+        resolveNoteId,
+        resolveCategoryId,
+        resolveProjectId,
+        invalidate,
+    };
+};
+// ---------------------------------------------------------------------------
+// Tag + Layer
+// ---------------------------------------------------------------------------
+export class Resolver extends Context.Tag('Resolver')() {
+    /**
+     * Default layer composes `Resolver` from the ambient `Api` service. Tests can
+     * provide an alternate layer via {@link layer}.
+     */
+    static Default = Layer.effect(Resolver, Effect.gen(function* () {
+        const api = yield* Api;
+        return make(api);
+    }));
+}
+/** Build a Resolver layer from an explicit `ApiService` (tests). */
+export const layer = (api, deps = {}) => Layer.succeed(Resolver, make(api, deps));

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

@@ -0,0 +1,29 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { ChapterNotFound, SkillCorpusEmpty } from '../domain/errors';
+export type ChapterSource = 'cli' | 'haklex';
+export interface Chapter {
+    readonly slug: string;
+    readonly title: string;
+    readonly description: string;
+    readonly order: number;
+    readonly source: ChapterSource;
+    readonly body: string;
+}
+export interface SearchHit {
+    readonly slug: string;
+    readonly title: string;
+    readonly description: string;
+    readonly snippets: readonly string[];
+}
+export interface SkillService {
+    readonly list: Effect.Effect<readonly Chapter[], SkillCorpusEmpty>;
+    readonly get: (slug: string) => Effect.Effect<Chapter, ChapterNotFound | SkillCorpusEmpty>;
+    readonly all: Effect.Effect<readonly Chapter[], SkillCorpusEmpty>;
+    readonly search: (keyword: string) => Effect.Effect<readonly SearchHit[], SkillCorpusEmpty>;
+}
+declare const Skill_base: Context.TagClass<Skill, "Skill", SkillService>;
+export declare class Skill extends Skill_base {
+    static Default: Layer.Layer<Skill, never, FileSystem.FileSystem | Path.Path>;
+}
+export {};