codz-cli 0.0.0-stage → 0.1.0

package/dist/skills/apiImport.js

@@ -0,0 +1,127 @@
+// api import: every operation in an OpenAPI, Swagger, Postman or HAR file,
+// planned one after another into a single change set. Each endpoint builds on
+// the files and models planned before it, so shared schemas become one model
+// and endpoints of one resource land in one file.
+//
+// Filters: --tag, --only, --path <glob>, --method, --max. --list shows what
+// would be imported and stops. Endpoints that cannot be planned (a model name
+// clash, say) stop the import unless --skip-conflicts applies the rest.
+import { join } from 'node:path';
+import { loadMap } from "../core/cache.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { loadConfig } from "../core/config.js";
+import { readText } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { readApiFile } from "../input/apiSpec.js";
+export const LARGE = 50;
+/** Glob for API paths: * matches one segment, ** any number; {id} and :id match any parameter. */
+export function pathMatches(glob, path) {
+    const norm = (p) => p.replace(/:([\w.-]+)/g, '{$1}').replace(/\/+$/, '') || '/';
+    const g = norm(glob.startsWith('/') ? glob : `/${glob}`);
+    const re = g
+        .split('/')
+        .map((seg) => (seg === '**' ? '\u0000' : seg === '*' ? '[^/]+' : /^\{[^/]+\}$/.test(seg) ? '\\{[^/]+\\}' : seg.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')))
+        .join('/')
+        .replace(/\/\u0000/g, '(?:/.*)?')
+        .replace(/\u0000/g, '.*');
+    return new RegExp(`^${re}$`).test(norm(path));
+}
+function readOperations(opts) {
+    const text = readText(opts.file);
+    if (text === null)
+        throw new ToolError('no_file', `Cannot read ${opts.file}.`);
+    const doc = readApiFile(text, { includeErrors: opts.includeErrors, baseUrl: opts.baseUrl });
+    const wantTags = new Set((opts.tags ?? []).map((t) => t.toLowerCase()));
+    const wantNames = new Set((opts.only ?? []).map((n) => n.toLowerCase()));
+    const wantMethods = new Set((opts.methods ?? []).map((m) => m.toUpperCase()));
+    let ops = doc.operations.filter((o) => (!wantTags.size || o.tags.some((t) => wantTags.has(t.toLowerCase()))) &&
+        (!wantNames.size || wantNames.has(o.spec.name.toLowerCase())) &&
+        (!wantMethods.size || wantMethods.has(o.spec.method)) &&
+        (!opts.paths?.length || opts.paths.some((g) => pathMatches(g, o.spec.path))));
+    if (!ops.length) {
+        const filtered = wantTags.size || wantNames.size || wantMethods.size || opts.paths?.length;
+        throw new ToolError('no_endpoints', `No operations matched in ${opts.file} (${doc.operations.length} in the file).`, filtered ? 'Check the --tag, --only, --method and --path values, or see everything with --list.' : undefined);
+    }
+    if (opts.max !== undefined) {
+        if (ops.length > opts.max)
+            doc.warnings.push(`Importing the first ${opts.max} of ${ops.length} matching operations (--max ${opts.max}).`);
+        ops = ops.slice(0, opts.max);
+    }
+    return { doc, ops };
+}
+/** --list: what the file holds after filters, without planning anything. */
+export function listApiImport(opts) {
+    const { doc, ops } = readOperations(opts);
+    return {
+        format: doc.format,
+        title: doc.title,
+        total: doc.operations.length,
+        operations: ops.map((o) => ({ name: o.spec.name, method: o.spec.method, path: o.spec.path, tags: o.tags, source: o.source, response: o.spec.response ? (o.spec.response.kind === 'object' ? o.spec.response.model : o.spec.response.kind === 'array' && o.spec.response.item.kind === 'object' ? `${o.spec.response.item.model}[]` : o.spec.response.kind) : undefined })),
+        warnings: doc.warnings,
+    };
+}
+export async function planApiImport(root, adapter, opts) {
+    if (!adapter.planEndpoint)
+        throw new ToolError('not_supported', `api import needs a framework adapter; this project uses the ${adapter.id} adapter.`);
+    const file = readText(join(root, opts.file)) !== null ? join(root, opts.file) : opts.file;
+    const { doc, ops } = readOperations({ ...opts, file });
+    if (ops.length > LARGE && opts.max === undefined && !opts.yes) {
+        throw new ToolError('too_many_endpoints', `${ops.length} operations matched, more than ${LARGE} in one change.`, `Narrow it with --tag, --path or --method, cap it with --max <n>, or pass --yes to import all ${ops.length}. See them first with --list.`);
+    }
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const working = structuredClone(map);
+    let overlay = new Map();
+    const added = [];
+    const existing = [];
+    const skipped = [];
+    const warnings = new Set(doc.warnings);
+    const generated = [];
+    for (const [i, op] of ops.entries()) {
+        opts.onProgress?.(i, ops.length, op.spec.name);
+        try {
+            const edits = await adapter.planEndpoint({ root, map: working }, op.spec, overlay);
+            if (!edits.endpoints) {
+                existing.push(op.spec.name);
+                continue;
+            }
+            overlay = edits.files;
+            working.endpoints.push(...edits.endpoints);
+            working.models.push(...(edits.models ?? []));
+            generated.push(...edits.generated);
+            for (const w of edits.warnings) {
+                // Per-endpoint reuse notes are noise in a bulk import.
+                // Project-wide notes (a missing package, say) are shown once, not per operation.
+                if (/^Reusing the existing model/.test(w))
+                    continue;
+                if (/is not in pubspec\.yaml|is not in package\.json/.test(w))
+                    warnings.add(w);
+                else
+                    warnings.add(`${op.spec.name}: ${w}`);
+            }
+            added.push(op.spec.name);
+        }
+        catch (e) {
+            if (!(e instanceof ToolError))
+                throw e;
+            skipped.push({ name: op.spec.name, reason: e.hint ? `${e.message} ${e.hint}` : e.message });
+        }
+    }
+    opts.onProgress?.(ops.length, ops.length, '');
+    if (skipped.length && !opts.skipConflicts) {
+        throw new ToolError('import_conflicts', `${skipped.length} of ${ops.length} operations cannot be added, so nothing was planned:\n${skipped.map((s) => `    ${s.name}: ${s.reason}`).join('\n')}`, `Pass --skip-conflicts to import the other ${ops.length - skipped.length}, or leave those out with --only / --path.`);
+    }
+    const label = { openapi: 'OpenAPI', swagger: 'Swagger', postman: 'Postman', har: 'HAR' }[doc.format];
+    const summary = [
+        `Import ${ops.length} operation${ops.length === 1 ? '' : 's'} from "${doc.title}" (${label}): ${added.length} added, ${existing.length} already present, ${skipped.length} skipped`,
+        ...added.map((n) => {
+            const ep = working.endpoints.find((e) => e.name === n);
+            return `  ${ep.method.padEnd(6)} ${ep.path}  →  ${n}()  in ${ep.file}`;
+        }),
+    ];
+    for (const s of skipped)
+        warnings.add(`Skipped ${s.name}: ${s.reason}`);
+    if (doc.format === 'har')
+        warnings.add('Response bodies from the HAR file were used only to work out types; none of their values were written.');
+    const changeSet = buildChangeSet(root, 'api import', { files: overlay, summary, warnings: [...warnings], generated });
+    return { changeSet, added, existing, skipped };
+}

package/dist/skills/apiList.js

@@ -0,0 +1,35 @@
+// api list and api show: what endpoints the project has, read from the project map.
+import { loadMap } from "../core/cache.js";
+import { loadConfig } from "../core/config.js";
+import { ToolError } from "../core/types.js";
+import { endpointUses } from "./apiEdit.js";
+export async function apiList(root, adapter, opts = {}) {
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const f = opts.filter?.toLowerCase();
+    return map.endpoints
+        .filter((e) => !f || e.name.toLowerCase().includes(f) || e.path.toLowerCase().includes(f) || e.method.toLowerCase() === f)
+        .map((e) => ({ ...e, uses: new Set(e.calledFrom).size }))
+        .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+export async function apiShow(root, adapter, name) {
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const ep = map.endpoints.find((e) => e.name === name) ?? map.endpoints.find((e) => e.name.toLowerCase() === name.toLowerCase());
+    if (!ep) {
+        const close = map.endpoints.filter((e) => e.name.toLowerCase().includes(name.toLowerCase())).map((e) => e.name);
+        throw new ToolError('no_endpoint', `No endpoint called ${name} was found.`, close.length ? `Did you mean: ${close.join(', ')}?` : 'List them with: codz api list');
+    }
+    // Models the response mentions, and the models those refer to.
+    const models = [];
+    const visit = (type) => {
+        for (const m of map.models) {
+            if (models.includes(m) || !new RegExp(`\\b${m.name}\\b`).test(type))
+                continue;
+            models.push(m);
+            for (const f of m.fields)
+                visit(f.type);
+        }
+    };
+    visit(ep.response ?? '');
+    const u = endpointUses(root, adapter, ep);
+    return { endpoint: ep, declLine: u.declLine, signature: u.signature, models, uses: u.uses };
+}

package/dist/skills/apiSync.js

@@ -0,0 +1,221 @@
+// api sync <spec>: brings the project's endpoints in line with an OpenAPI,
+// Swagger, Postman or HAR file in one change.
+//
+//   in both          rewritten from the spec (response and request models,
+//                    parameters); unchanged ones are left alone
+//   only in spec     listed; added with --add
+//   only in project  listed; removed with --remove
+//
+// Breaking changes (a response field removed or changed type, a new required
+// parameter) are reported with the lines that use them. --check plans
+// everything and reports drift without writing (exit 1 when out of sync).
+import { join } from 'node:path';
+import { loadMap } from "../core/cache.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { loadConfig } from "../core/config.js";
+import { readText } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { readApiFile } from "../input/apiSpec.js";
+import { findDeclaration, planApiRemove, planEndpointUpdate } from "./apiEdit.js";
+import { pathMatches } from "./apiImport.js";
+const shape = (p) => p.replace(/\{[^/}]+\}/g, '{}').replace(/\/+$/, '') || '/';
+/** The spec operation for a project endpoint: same method, and the same path or the same path under a base prefix (/v1). */
+function matchOperation(ep, ops) {
+    const same = ops.filter((o) => o.spec.method === ep.method);
+    const p = shape(ep.path);
+    return same.find((o) => shape(o.spec.path) === p) ?? same.find((o) => shape(o.spec.path).endsWith(p) && p !== '/');
+}
+function renameModel(t, from, to) {
+    if (!t)
+        return t;
+    if (t.kind === 'object')
+        return t.model === from ? { kind: 'object', model: to } : t;
+    if (t.kind === 'array')
+        return { kind: 'array', item: renameModel(t.item, from, to) };
+    return t;
+}
+function rootModel(t) {
+    if (!t)
+        return undefined;
+    if (t.kind === 'object')
+        return t.model;
+    if (t.kind === 'array')
+        return rootModel(t.item);
+    return undefined;
+}
+export async function planApiSync(root, adapter, opts) {
+    if (!adapter.planEndpoint)
+        throw new ToolError('not_supported', `api sync needs a framework adapter; this project uses the ${adapter.id} adapter.`);
+    const file = readText(join(root, opts.file)) !== null ? join(root, opts.file) : opts.file;
+    const text = readText(file);
+    if (text === null)
+        throw new ToolError('no_file', `Cannot read ${opts.file}.`);
+    const doc = readApiFile(text, { baseUrl: opts.baseUrl });
+    const wantTags = new Set((opts.tags ?? []).map((t) => t.toLowerCase()));
+    const ops = doc.operations.filter((o) => (!wantTags.size || o.tags.some((t) => wantTags.has(t.toLowerCase()))) && (!opts.paths?.length || opts.paths.some((g) => pathMatches(g, o.spec.path))));
+    if (!ops.length)
+        throw new ToolError('no_endpoints', `No operations matched in ${opts.file}.`);
+    const lang = adapter.id === 'flutter' ? 'dart' : 'ts';
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const suffix = lang === 'dart' ? map.conventions.modelClassSuffix ?? '' : '';
+    const working = structuredClone(map);
+    let overlay = new Map();
+    const report = { updated: [], unchanged: [], added: [], newInSpec: [], removed: [], missingFromSpec: [], breaking: [] };
+    const summary = [];
+    const warnings = new Set(doc.warnings);
+    const generated = [];
+    const matched = new Set();
+    // Prefixes the project's paths leave out (/v1 when the base URL already has it), learned from matches.
+    const prefixes = new Map();
+    // With path filters, only endpoints under those paths are compared.
+    const inScope = (ep) => !opts.paths?.length || opts.paths.some((g) => pathMatches(g, ep.path) || ops.some((o) => shape(o.spec.path).endsWith(shape(ep.path))));
+    for (const ep of map.endpoints.filter(inScope)) {
+        const op = matchOperation(ep, ops);
+        if (!op) {
+            report.missingFromSpec.push(ep.name);
+            continue;
+        }
+        matched.add(op);
+        const specShape = shape(op.spec.path);
+        const prefix = specShape.slice(0, specShape.length - shape(ep.path).length);
+        prefixes.set(prefix, (prefixes.get(prefix) ?? 0) + 1);
+        const spec = structuredClone(op.spec);
+        spec.name = ep.name;
+        // The project's path (relative to its base URL) and parameter names stay; the spec decides types.
+        const projectParams = [...ep.path.matchAll(/\{([^/}]+)\}/g)].map((m) => m[1]);
+        if (projectParams.length === spec.pathParams.length)
+            spec.pathParams = spec.pathParams.map((p, i) => ({ ...p, name: projectParams[i] }));
+        spec.path = ep.path;
+        spec.origin = '';
+        delete spec.serverPrefix;
+        // Fields the project already has keep their order, so the diff shows only what changed.
+        for (const m of spec.models) {
+            const old = map.models.find((x) => x.name === (suffix && !m.name.endsWith(suffix) ? m.name + suffix : m.name));
+            if (!old)
+                continue;
+            const order = new Map(old.fields.map((f, i) => [f.name, i]));
+            m.fields = [...m.fields].sort((a, b) => (order.get(a.jsonName) ?? 1e6) - (order.get(b.jsonName) ?? 1e6));
+        }
+        // The project's response class keeps its name (the spec may call it UserDto).
+        const rootClass = (ep.response ?? '').replace(/^Promise<(.*)>$/, '$1').replace(/^List<(.*)>$/, '$1').replace(/\[\]$/, '').replace(/\?$/, '');
+        const specRoot = rootModel(spec.response);
+        const keep = rootClass && map.models.some((m) => m.name === rootClass) ? (suffix && rootClass.endsWith(suffix) ? rootClass.slice(0, -suffix.length) : rootClass) : undefined;
+        if (specRoot && keep && specRoot !== keep && !spec.models.some((m) => m.name === keep)) {
+            spec.response = renameModel(spec.response, specRoot, keep);
+            for (const m of spec.models) {
+                if (m.name === specRoot)
+                    m.name = keep;
+                m.fields = m.fields.map((f) => ({ ...f, type: renameModel(f.type, specRoot, keep) }));
+            }
+        }
+        const before = new Map(overlay);
+        try {
+            const r = await planEndpointUpdate(root, adapter, working, overlay, ep, spec, rootClass, `from ${doc.format === 'har' ? 'the HAR file' : 'the spec'}`);
+            const changedFiles = [...r.files].filter(([f, t]) => (before.get(f) ?? readText(join(root, f))) !== t);
+            if (!changedFiles.length) {
+                report.unchanged.push(ep.name);
+                continue;
+            }
+            overlay = r.files;
+            report.updated.push(ep.name);
+            summary.push(...r.summary);
+            for (const w of r.warnings)
+                warnings.add(`${ep.name}: ${w}`);
+            generated.push(...r.generated);
+            for (const m of r.models) {
+                const i = working.models.findIndex((x) => x.name === m.name);
+                if (i === -1)
+                    working.models.push(m);
+                else
+                    working.models[i] = m;
+            }
+            if (r.changes.removed.length)
+                report.breaking.push(`${ep.name}: ${rootClass || 'response'} lost ${r.changes.removed.join(', ')}`);
+            // A field that became non-nullable is not breaking for code that reads it; anything else is.
+            const risky = r.changes.changed.filter((c) => {
+                const m = /^[^:]+:\s*(.+?)\s*→\s*(.+)$/.exec(c);
+                return !m || !(m[1].replace(/\?$/, '') === m[2].replace(/\?$/, '') && m[1].endsWith('?') && !m[2].endsWith('?'));
+            });
+            if (risky.length)
+                report.breaking.push(`${ep.name}: ${risky.join('; ')}`);
+            const oldText = readText(join(root, ep.file)) ?? '';
+            const oldDecl = findDeclaration(oldText, ep.name, lang)?.params ?? '';
+            const newPathParams = spec.pathParams.map((p) => p.name).filter((n) => !new RegExp(`\\b${n}\\b`).test(oldDecl));
+            if (newPathParams.length)
+                report.breaking.push(`${ep.name}: new required parameter${newPathParams.length === 1 ? '' : 's'} ${newPathParams.join(', ')}`);
+            if (spec.request && !/\bbody\b/.test(oldDecl))
+                report.breaking.push(`${ep.name}: now takes a request body`);
+        }
+        catch (e) {
+            if (!(e instanceof ToolError))
+                throw e;
+            warnings.add(`Could not update ${ep.name}: ${e.message}`);
+        }
+    }
+    // New in the spec.
+    for (const op of ops) {
+        if (matched.has(op))
+            continue;
+        if (working.endpoints.some((e) => e.name === op.spec.name && e.method === op.spec.method))
+            continue;
+        if (!opts.add) {
+            report.newInSpec.push(op.spec.name);
+            continue;
+        }
+        try {
+            const spec = structuredClone(op.spec);
+            const [prefix] = [...prefixes.entries()].sort((a, b) => b[1] - a[1])[0] ?? [''];
+            if (prefix && spec.path.startsWith(`${prefix}/`)) {
+                spec.path = spec.path.slice(prefix.length);
+                spec.origin = '';
+                delete spec.serverPrefix;
+            }
+            const edits = await adapter.planEndpoint({ root, map: working }, spec, overlay);
+            if (!edits.endpoints)
+                continue;
+            overlay = edits.files;
+            working.endpoints.push(...edits.endpoints);
+            working.models.push(...(edits.models ?? []));
+            generated.push(...edits.generated);
+            report.added.push(op.spec.name);
+            summary.push(`Add ${spec.name}() for ${spec.method} ${spec.path}`);
+        }
+        catch (e) {
+            if (!(e instanceof ToolError))
+                throw e;
+            warnings.add(`Could not add ${op.spec.name}: ${e.message}`);
+        }
+    }
+    // Gone from the spec.
+    if (opts.remove && report.missingFromSpec.length) {
+        for (const name of report.missingFromSpec) {
+            // Removal works on files as they are on disk; it is planned only when the file is not also being updated.
+            const ep = map.endpoints.find((e) => e.name === name);
+            if (overlay.has(ep.file)) {
+                warnings.add(`${name} is not in the spec, but ${ep.file} also has updates; run api remove ${name} after this sync.`);
+                continue;
+            }
+            const cs = await planApiRemove(root, adapter, name);
+            for (const ch of cs.changes)
+                if (ch.after !== null)
+                    overlay.set(ch.path, ch.after);
+            summary.push(...cs.summary);
+            for (const w of cs.warnings)
+                warnings.add(w);
+            report.removed.push(name);
+        }
+    }
+    if (report.newInSpec.length)
+        warnings.add(`In the spec but not in the project: ${report.newInSpec.join(', ')}. Pass --add to add them.`);
+    const notRemoved = report.missingFromSpec.filter((n) => !report.removed.includes(n));
+    if (notRemoved.length && !opts.remove)
+        warnings.add(`In the project but not in the spec: ${notRemoved.join(', ')}. Pass --remove to delete them (only if they belong to this API).`);
+    if (report.breaking.length)
+        warnings.add(`Breaking changes for callers:\n${report.breaking.map((b) => `    ${b}`).join('\n')}`);
+    if (!summary.length)
+        summary.push(`Everything matches ${opts.file}: ${report.unchanged.length} endpoint${report.unchanged.length === 1 ? '' : 's'} checked.`);
+    else
+        summary.unshift(`Sync with ${doc.title || opts.file}: ${report.updated.length} updated, ${report.added.length} added, ${report.removed.length} removed, ${report.unchanged.length} unchanged`);
+    const changeSet = buildChangeSet(root, 'api sync', { files: overlay, summary, warnings: [...warnings], generated });
+    return { changeSet, ...report };
+}