octwin-cli 0.3.0 → 0.6.0

package/dist/lib/template-check.js

@@ -0,0 +1,107 @@
+/**
+ * Offline `use:` template check, driven by the pulled platform KB.
+ *
+ * WHY it matters: `use:` splices a template's NODES into the flow at load time,
+ * before any expression evaluates, and its `with:` block is the only thing the
+ * spliced subtree can see. So a mistyped param name does not error — it arrives
+ * as `undefined` inside the template body, and the card renders with a blank
+ * where the value should be, or a confirm step approves with no preview. The
+ * platform's own `approve_apply` is the common case: `confirm_title` misspelled
+ * silently falls back to the hardcoded Arabic default.
+ *
+ * PACK TEMPLATES SHADOW PLATFORM ONES. A pack may ship `templates/<name>.yaml`
+ * of its own, and a pack template of the same name wins. So the caller passes
+ * the pack's own template names and this check stays silent about them entirely
+ * — it has no schema for a template it did not publish, and inventing one would
+ * flag every pack that uses its own.
+ *
+ * WHAT IT DOES NOT CHECK: a pack template's params (no published schema, see
+ * above), and the VALUES passed to a platform template's params — a `with:`
+ * value is almost always an expression resolved at runtime, exactly as in
+ * `args-check.ts`.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
+/** Load platform template param specs from the pulled KB. */
+export function loadTemplateSpecs(packDir) {
+    const lookup = lookupKbSubdir(packDir, 'templates', dir => readdirSync(dir).some(isEntryFile));
+    if (lookup.state !== 'ok')
+        return { lookup, specs: null };
+    const dir = lookup.dir;
+    const out = new Map();
+    try {
+        for (const file of readdirSync(dir)) {
+            if (!isEntryFile(file))
+                continue;
+            const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            if (!entry.name)
+                continue;
+            const params = Array.isArray(entry.params) ? entry.params : [];
+            out.set(entry.name, {
+                name: entry.name,
+                params: params.map(p => p.name).filter((n) => !!n),
+                required: params.filter(p => p.required === true).map(p => p.name).filter((n) => !!n),
+            });
+        }
+    }
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, specs: null };
+    }
+    if (!out.size)
+        return { lookup: { state: 'malformed', dir, reason: 'no template entries parsed' }, specs: null };
+    return { lookup, specs: out };
+}
+/**
+ * Walk parsed YAML for `use:` nodes and check them against the platform specs.
+ * `packTemplates` names the templates this pack ships itself — those are skipped.
+ */
+export function findTemplateViolations(doc, file, specs, packTemplates) {
+    const findings = [];
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        const obj = node;
+        const name = obj.use;
+        if (typeof name === 'string' && !packTemplates.has(name)) {
+            const spec = specs.get(name);
+            if (!spec) {
+                findings.push({ kind: 'unknown', file, template: name, known: [...specs.keys()].sort() });
+            }
+            else {
+                const withBlock = obj.with;
+                const passed = withBlock && typeof withBlock === 'object' && !Array.isArray(withBlock)
+                    ? Object.keys(withBlock)
+                    : [];
+                const unknown = passed.filter(k => !spec.params.includes(k));
+                if (unknown.length)
+                    findings.push({ kind: 'unknown-param', file, template: name, keys: unknown, params: [...spec.params].sort() });
+                const missing = spec.required.filter(k => !passed.includes(k));
+                if (missing.length)
+                    findings.push({ kind: 'missing', file, template: name, keys: missing });
+            }
+        }
+        for (const v of Object.values(obj))
+            walk(v);
+    };
+    walk(doc);
+    return findings;
+}
+/** One-line human message per finding. */
+export function describeTemplateFinding(f) {
+    switch (f.kind) {
+        case 'unknown':
+            return `${f.file}: \`use: ${f.template}\` — no such template. Platform templates: ${f.known.join(', ')}`
+                + `. (A template of your own must live at templates/${f.template}.yaml in the pack.)`;
+        case 'unknown-param':
+            return `${f.file}: \`use: ${f.template}\` passes ${f.keys.map(k => `'${k}'`).join(', ')}, which the template declares no param for `
+                + `— dropped in silence, and the body sees undefined. Params: ${f.params.join(', ')}`;
+        case 'missing':
+            return `${f.file}: \`use: ${f.template}\` is missing required param${f.keys.length === 1 ? '' : 's'} `
+                + `${f.keys.map(k => `'${k}'`).join(', ')} — the body reads undefined where the value should be`;
+    }
+}

package/dist/lib/validate.js

@@ -14,6 +14,33 @@
  * every rule, so a divergence fails the build rather than surfacing as "it passed
  * locally but the deploy rejected it".
  */
+/**
+ * The pack-name grammar, vendored from `src/platform/core/kernel/pack-id.ts`.
+ *
+ * Your `manifest.yaml` declares a BARE name (`clinic`). The platform prefixes your
+ * workspace slug when it publishes, so the pack becomes `acme.clinic` in the catalog
+ * — you never write the owner half, and therefore cannot claim someone else's.
+ */
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+/** Validate a raw string as a pack name, or `null`. The only way to mint a `PackName`. */
+export function asPackName(raw) {
+    return describePackNameProblem(raw) === null ? raw : null;
+}
+/** Why the manifest's `id` is unusable, or null. Prose, because an author reads it. */
+export function describePackNameProblem(name) {
+    if (!name)
+        return 'manifest.yaml must declare a non-empty `id`';
+    if (name.includes('.')) {
+        return `pack id '${name}' must not contain '.' — declare the bare name ` +
+            `('${name.slice(name.indexOf('.') + 1)}'); the platform prefixes your workspace ` +
+            `when it publishes`;
+    }
+    if (!SLUG_RE.test(name)) {
+        return `pack id '${name}' must be lowercase letters, digits and inner hyphens, ` +
+            `1–40 chars (e.g. 'clinic')`;
+    }
+    return null;
+}
 /** Declarative TEXT extensions a pure-YAML pack may contain. */
 const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'json']);
 /** Binary extensions that travel as artifact BLOBS (base64 on the wire, bytea in
@@ -39,13 +66,15 @@ function ext(p) {
  * no path traversal or absolute paths, declarative extensions only. Returns all
  * violations at once.
  */
-export function validatePackBundle(packId, files, 
+export function validatePackBundle(
+/** The manifest's BARE name — the platform prefixes your workspace at publish. */
+packName, files, 
 /** `{ relPath: base64 }` — the binary half, as the CLI collects it. */
 blobs = {}) {
     const errors = [];
-    if (!/^[a-z][a-z0-9-]*$/.test(packId)) {
-        errors.push(`pack id '${packId}' must be lowercase ASCII with hyphens (e.g. 'my-pack')`);
-    }
+    const idProblem = describePackNameProblem(packName);
+    if (idProblem)
+        errors.push(idProblem);
     const paths = Object.keys(files);
     if (paths.length === 0 && Object.keys(blobs).length === 0)
         errors.push('bundle is empty');

package/dist/lib/yaml-pos.js

@@ -0,0 +1,29 @@
+/**
+ * YAML source line for a node path — the CLI-side twin of the platform's
+ * `core/utils/yaml-position.ts` (E-08). Standalone because the CLI is
+ * platform-free by construction; both are ~40 lines over the same `yaml` API.
+ *
+ * `yamlLineOf(raw, path)` parses once per call — fine here, because findings
+ * are rare (the happy path calls this zero times). When the exact node doesn't
+ * resolve, walks up the path so the enclosing node's line is reported.
+ */
+import { LineCounter, parseDocument } from 'yaml';
+export function yamlLineOf(raw, path) {
+    const lineCounter = new LineCounter();
+    let doc;
+    try {
+        doc = parseDocument(raw, { lineCounter, keepSourceTokens: true });
+    }
+    catch {
+        return null;
+    }
+    for (let end = path.length; end >= 0; end--) {
+        const node = end === 0
+            ? doc.contents
+            : doc.getIn(path.slice(0, end), true);
+        const start = node?.range?.[0];
+        if (typeof start === 'number')
+            return lineCounter.linePos(start).line;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {