@notis_ai/cli 0.2.18 → 0.2.19

package/src/runtime/space-database-structures.js

@@ -0,0 +1,229 @@
+/** Refresh only pulled database creation declarations; never execute authored code. */
+import { parse } from '@babel/parser';
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { usageError } from './errors.js';
+
+const nameOf = node => node?.type === 'Identifier' ? node.name : node?.type === 'StringLiteral' ? node.value : null;
+
+export function refreshDatabaseStructures(projectDir, localKey, structures) {
+  return refreshSpaceAuthoring(projectDir, localKey, { databaseStructures: structures });
+}
+
+/** Exact current-host overrides for copied source. Archives remain byte-preserved. */
+export function refreshSpaceAuthoring(projectDir, localKey, { databaseStructures, authoringOverrides } = {}) {
+  let rewritten = new Map();
+  if (Object.keys(databaseStructures || {}).length) rewritten = planSpaceAuthoring(projectDir, localKey, { databaseStructures }, rewritten);
+  if (authoringOverrides) rewritten = planSpaceAuthoring(projectDir, localKey, { authoringOverrides }, rewritten);
+  // Both stages must succeed before mutating even one downloaded file.
+  for (const [file, source] of rewritten) writeFileSync(file, source);
+  return [...rewritten.keys()].map(file => relative(realpathSync(projectDir), file).split(sep).join('/'));
+}
+
+function planSpaceAuthoring(projectDir, localKey, { databaseStructures: structures, authoringOverrides: overrides }, staged) {
+  const root = realpathSync(projectDir), modules = new Map();
+  const fail = () => usageError('The pulled database declaration is not statically addressable. Keep resources and create declarations as objects, local constants or relative imports; the downloaded source has not been rewritten.');
+  function load(file) {
+    file = realpathSync(file);
+    if (!file.startsWith(root + sep) || file.includes(`${sep}node_modules${sep}`)) throw fail();
+    if (modules.has(file)) return modules.get(file);
+    const source = staged.get(file) ?? readFileSync(file, 'utf8');
+    const ast = parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] });
+    const unit = { file, source, ast, bindings: new Map(), exports: new Map() };
+    modules.set(file, unit);
+    for (const statement of ast.program.body) {
+      const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+      if (declaration?.type === 'VariableDeclaration') {
+        for (const item of declaration.declarations) if (item.id.type === 'Identifier' && item.init) {
+          unit.bindings.set(item.id.name, { node: item.init, unit });
+          if (statement.type === 'ExportNamedDeclaration') unit.exports.set(item.id.name, { node: item.init, unit });
+        }
+      }
+      if (statement.type === 'ImportDeclaration') {
+        for (const item of statement.specifiers) unit.bindings.set(item.local.name, {
+          imported: item.type === 'ImportDefaultSpecifier' ? 'default' : item.type === 'ImportNamespaceSpecifier' ? '*' : nameOf(item.imported),
+          from: statement.source.value, unit,
+        });
+      }
+      if (statement.type === 'ExportDefaultDeclaration') unit.exports.set('default', { node: statement.declaration, unit });
+      if (statement.type === 'ExportNamedDeclaration') for (const item of statement.specifiers || []) {
+        unit.exports.set(nameOf(item.exported), statement.source
+          ? { imported: nameOf(item.local), from: statement.source.value, unit }
+          : { node: item.local, unit });
+      }
+    }
+    return unit;
+  }
+  function imported(reference) {
+    if (!reference.from?.startsWith('.')) throw fail();
+    const base = resolve(dirname(reference.unit.file), reference.from);
+    const file = ['', '.ts', '.tsx', '.js', '.mjs', '/index.ts', '/index.js'].map(suffix => base + suffix).find(existsSync);
+    if (!file) throw fail();
+    return load(file);
+  }
+  function unwrap(reference, depth = 0) {
+    if (!reference || depth > 50) throw fail();
+    if (reference.from) {
+      if (reference.imported === '*') return { namespace: imported(reference) };
+      return unwrap(imported(reference).exports.get(reference.imported), depth + 1);
+    }
+    const { node, unit } = reference;
+    if (node.type === 'Identifier') return unwrap(unit.bindings.get(node.name), depth + 1);
+    if (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ParenthesizedExpression', 'TSTypeAssertion'].includes(node.type)) {
+      return unwrap({ node: node.expression, unit }, depth + 1);
+    }
+    if (node.type === 'CallExpression' && node.arguments.length === 1 && node.callee.type === 'Identifier') {
+      const helper = unit.bindings.get(node.callee.name);
+      if (helper?.from === '@notis/sdk/config' && ['defineSpace', 'defineSpaces'].includes(helper.imported)) {
+        return unwrap({ node: node.arguments[0], unit }, depth + 1);
+      }
+    }
+    if (node.type === 'MemberExpression' && (!node.computed || node.property.type === 'StringLiteral')) {
+      const object = unwrap({ node: node.object, unit }, depth + 1);
+      return object.namespace ? unwrap(object.namespace.exports.get(nameOf(node.property)), depth + 1)
+        : unwrap(property(object, nameOf(node.property), depth + 1), depth + 1);
+    }
+    return reference;
+  }
+  function property(reference, name, depth = 0) {
+    const object = unwrap(reference, depth + 1);
+    if (object.node?.type !== 'ObjectExpression') throw fail();
+    // Later properties/spreads win, exactly as the authored object does.
+    for (const entry of [...object.node.properties].reverse()) {
+      if (entry.type === 'SpreadElement') {
+        const found = property({ node: entry.argument, unit: object.unit }, name, depth + 1);
+        if (found) return found;
+      } else if (entry.type === 'ObjectProperty' && !entry.computed && nameOf(entry.key) === name) {
+        return { node: entry.value, unit: object.unit };
+      }
+    }
+    return null;
+  }
+  function scalar(reference) {
+    const value = unwrap(reference);
+    if (value.node?.type !== 'StringLiteral') throw fail();
+    return value.node.value;
+  }
+  const indexFile = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'].map(file => join(root, file)).find(existsSync);
+  if (!indexFile) throw fail();
+  const index = load(indexFile);
+  const workspace = index.exports.get('default');
+  const definition = scalar(property(property(property(workspace, 'spaces'), localKey), 'definition'));
+  const unit = load(resolve(root, definition));
+  const resources = property(unit.exports.get('default'), 'resources');
+  const edits = new Map();
+  for (const [alias, structure] of Object.entries(structures || {})) {
+    if (!structure || typeof structure.name !== 'string' || !structure.schema || typeof structure.schema !== 'object' || Array.isArray(structure.schema)) throw usageError('The server returned an incomplete live database structure.');
+    const resource = property(resources, alias);
+    if (scalar(property(resource, 'kind')) !== 'database') throw fail();
+    const create = property(resource, 'create');
+    if (!create || !Number.isInteger(create.node.start) || !Number.isInteger(create.node.end)) throw fail();
+    const list = edits.get(create.unit.file) || [];
+    // Inline declarations are edited in place. Constants retain their shared
+    // helper and get one explicit local override, not another wrapper per pull.
+    let node = create.node;
+    while (['TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression'].includes(node.type)) node = node.expression;
+    if (node.type === 'ObjectExpression') {
+      const additions = [];
+      for (const [name, value] of [['name', structure.name], ['schema', structure.schema]]) {
+        const field = [...node.properties].reverse().find(item => item.type === 'ObjectProperty' && !item.computed && nameOf(item.key) === name);
+        const replacement = JSON.stringify(value, null, 2);
+        if (field && !field.shorthand) list.push({ start: field.value.start, end: field.value.end, replacement });
+        else if (field) list.push({ start: field.start, end: field.end, replacement: `${name}: ${replacement}` });
+        else additions.push(`${name}: ${replacement}`);
+      }
+      if (additions.length) list.push({ start: node.end - 1, end: node.end - 1,
+        replacement: `${node.properties.length && !create.unit.source.slice(node.properties.at(-1).end, node.end - 1).includes(',') ? ',' : ''} ${additions.join(', ')} ` });
+    } else {
+      const original = create.unit.source.slice(create.node.start, create.node.end);
+      list.push({ start: create.node.start, end: create.node.end,
+        replacement: `({ ...(${original}), name: ${JSON.stringify(structure.name)}, schema: ${JSON.stringify(structure.schema, null, 2)} })` });
+    }
+    edits.set(create.unit.file, list);
+  }
+  if (overrides) {
+    if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)
+      || Object.keys(overrides).some(key => !['record_params', 'resource_keys'].includes(key))) throw fail();
+    const recordParams = overrides.record_params || {}, resourceKeys = overrides.resource_keys || {};
+    if ([recordParams, resourceKeys].some(value => !value || typeof value !== 'object' || Array.isArray(value))) throw fail();
+    // Pin authoring to this selected definition. Shared imports/constants are
+    // overridden at their local use site, never rewritten for sibling Spaces.
+    const rootDefinition = unwrap(unit.exports.get('default'));
+    if (rootDefinition.unit !== unit || rootDefinition.node.type !== 'ObjectExpression') throw fail();
+    const rawField = name => {
+      const field = [...rootDefinition.node.properties].reverse().find(item => item.type === 'ObjectProperty'
+        && !item.computed && nameOf(item.key) === name);
+      if (!field || field.shorthand) throw fail();
+      return { node: field.value, unit };
+    };
+    const text = reference => reference.unit.source.slice(reference.node.start, reference.node.end);
+    const patchObject = (reference, fields) => {
+      let node = reference.node;
+      while (['TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression'].includes(node.type)) node = node.expression;
+      if (node.type !== 'ObjectExpression') {
+        return `({ ...(${text(reference)}), ${Object.entries(fields).map(([key, value]) => `${JSON.stringify(key)}: ${value}`).join(', ')} })`;
+      }
+      let source = text(reference), changes = [], additions = [];
+      for (const [key, replacement] of Object.entries(fields)) {
+        const field = [...node.properties].reverse().find(item => item.type === 'ObjectProperty' && !item.computed && nameOf(item.key) === key);
+        if (field) changes.push({ start: (field.shorthand ? field.start : field.value.start) - reference.node.start,
+          end: (field.shorthand ? field.end : field.value.end) - reference.node.start,
+          replacement: field.shorthand ? `${JSON.stringify(key)}: ${replacement}` : replacement });
+        else additions.push(`${JSON.stringify(key)}: ${replacement}`);
+      }
+      if (additions.length) changes.push({ start: node.end - 1 - reference.node.start, end: node.end - 1 - reference.node.start,
+        replacement: `${node.properties.length && !reference.unit.source.slice(node.properties.at(-1).end, node.end - 1).includes(',') ? ',' : ''} ${additions.join(', ')} ` });
+      for (const change of changes.sort((a, b) => b.start - a.start)) source = source.slice(0, change.start) + change.replacement + source.slice(change.end);
+      return source;
+    };
+    const queue = (reference, replacement) => {
+      const list = edits.get(reference.unit.file) || [];
+      list.push({ start: reference.node.start, end: reference.node.end, replacement }); edits.set(reference.unit.file, list);
+    };
+    for (const [fieldName, requests] of [['params', recordParams], ['resources', resourceKeys]]) {
+      if (!Object.keys(requests).length) continue;
+      const reference = rawField(fieldName), object = unwrap(reference), replacements = {};
+      for (const [name, expected] of Object.entries(requests)) {
+        if (!expected || typeof expected !== 'object' || Array.isArray(expected)) throw fail();
+        const current = property(reference, name);
+        if (!current) throw fail();
+        const source = object.node.type === 'ObjectExpression' && object.unit === unit && current.unit === unit ? text(current)
+          : `(${text(reference)})[${JSON.stringify(name)}]`;
+        if (fieldName === 'params') {
+          if (Object.keys(expected).some(key => !['database', 'main'].includes(key)) || typeof expected.main !== 'boolean'
+            || scalar(property(current, 'type')) !== 'record' || scalar(property(current, 'database')) !== expected.database) throw fail();
+          replacements[name] = current.unit === unit && object.node.type === 'ObjectExpression'
+            ? patchObject(current, { main: JSON.stringify(expected.main) }) : `({ ...(${source}), main: ${JSON.stringify(expected.main)} })`;
+        } else {
+          if (Object.keys(expected).some(key => !['kind', 'key'].includes(key)) || typeof expected.key !== 'string' || !expected.key
+            || scalar(property(current, 'kind')) !== expected.kind) throw fail();
+          const create = property(current, 'create'), key = property(current, 'key');
+          if (create) {
+            // Copied source archives retain their original create declaration.
+            // A reused database (or one whose main moved) is now an existing
+            // binding: replace only this definition's resource, never a shared
+            // imported creation or a sibling view's source.
+            if (expected.kind !== 'database' || key) throw fail();
+            replacements[name] = JSON.stringify(expected);
+          } else {
+            if (!key) throw fail();
+            replacements[name] = current.unit === unit && object.node.type === 'ObjectExpression'
+              ? patchObject(current, { key: JSON.stringify(expected.key) }) : `({ ...(${source}), key: ${JSON.stringify(expected.key)} })`;
+          }
+        }
+      }
+      queue(reference, patchObject(reference, replacements));
+    }
+  }
+  const rewritten = new Map(staged);
+  for (const [file, list] of edits) {
+    let source = modules.get(file).source, previous = source.length;
+    for (const edit of list.sort((a, b) => b.start - a.start)) {
+      if (edit.end > previous) throw fail();
+      source = source.slice(0, edit.start) + edit.replacement + source.slice(edit.end); previous = edit.start;
+    }
+    parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] });
+    rewritten.set(file, source);
+  }
+  return rewritten;
+}

package/src/runtime/space-fixture-broker.js

@@ -0,0 +1,68 @@
+/** Pure fixture adapter for the exact CLI/service renderer; no network client. */
+import { createSpaceFixtureEngine, spaceHarnessSnapshot } from './space-test-server.js';
+import { usageError } from './errors.js';
+
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => object(value) && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+
+export function createSpaceFixtureBroker({ release, capabilities, width, outputs = ['markdown', 'screenshot'],
+  authorizationMode = 'authorize_missing', unavailableActions = [] }) {
+  const engine = createSpaceFixtureEngine(release);
+  const frozen = spaceHarnessSnapshot(release, capabilities, engine, { authorizationMode, unavailableActions });
+  const calls = [];
+  const params = structuredClone(engine.context.params || {});
+  // The fixture's own "now" pins the browser clock, so a view that asks for the
+  // last hour sends the exact inputs its fixtures recorded.
+  const now = engine.context.now;
+  const fixedClock = typeof now === 'string' && Number.isFinite(Date.parse(now)) ? { fixed_clock: now } : {};
+  const value = { ...frozen, url: `https://app.notis.ai/verification/${encodeURIComponent(release.manifest.local_key)}`,
+    view: { space_id: frozen.descriptor.resource.id, name: release.manifest.name, revision: 1 },
+    locale: engine.context.locale === 'fr' ? 'fr' : 'en', params,
+    markdownExport: release.manifest.markdown?.export_name || null, render_options: { outputs, width }, ...fixedClock };
+  return {
+    fixtureDigest: engine.digest,
+    calls,
+    async snapshot() { return structuredClone(value); },
+    async read(request) {
+      let result;
+      const log = { operation: request?.operation, ...(request?.action_id ? { actionId: request.action_id } : {}),
+        ...(typeof request?.record_key === 'string' ? { recordKey: request.record_key } : {}), ok: false };
+      calls.push(log);
+      try {
+        result = readFixture(request);
+      } catch (error) {
+        // Keep the reason with the call so verify reports which read failed and what the fixture lacks.
+        log.error = String(error?.message || error).slice(0, 2000);
+        throw error;
+      }
+      log.ok = true;
+      return result;
+    },
+    async finish() {
+      const failed = calls.find(value => !value.ok);
+      if (failed) throw usageError(failed.error ? `A synthetic fixture read failed: ${failed.error}` : 'A synthetic fixture read failed.');
+      return { valid: true };
+    },
+  };
+
+  function readFixture(request) {
+    let result;
+    if (calls.length > 256) throw usageError('The offline fixture read limit was reached.');
+    if (request?.operation === 'action' && exact(request, ['operation', 'action_id', 'inputs', 'request_id'])) {
+      if (frozen.descriptor.space.actions[request.action_id]?.readOnly !== true) throw usageError('Offline verification never runs write actions.');
+      result = engine.execute(request.action_id, request.inputs);
+    } else if (request?.operation === 'shown' && exact(request, ['operation', 'name', 'params', 'options'])) {
+      result = engine.executeShown(request.name, request.params, request.options);
+    } else if (request?.operation === 'viewer_read' && exact(request, ['operation', 'name', 'input'])) {
+      result = engine.executeViewerRead(request.name, request.input);
+    } else if (request?.operation === 'document_body' && exact(request, ['operation', 'record_key', 'binding', 'read_action'])) {
+      if (frozen.descriptor.space.actions[request.read_action]?.readOnly !== true) throw usageError('This document read action is unavailable.');
+      result = engine.executeBody({ operation: 'read', recordKey: request.record_key, binding: request.binding, readAction: request.read_action });
+    } else if (['record', 'html', 'report'].includes(request?.operation) && exact(request, ['operation', 'record_key'])) {
+      result = engine.executeRecordView(request.operation, request.record_key);
+    } else {
+      throw usageError('Only declared read-only synthetic fixtures are available.');
+    }
+    return result;
+  }
+}

package/src/runtime/space-lock.js

@@ -0,0 +1,337 @@
+/**
+ * Local record of a pulled Space: its resource list and the version of every
+ * editable Skill folder (R5).
+ *
+ * `notis spaces pull` writes the Space's links to `resources.json`, every
+ * editable linked Skill to `skills/<alias>/`, and this lock to
+ * `.notis/space-lock.json` (local-only state, never part of the portable
+ * source). `notis spaces deploy` compares the working tree with the lock and
+ * sends only what changed since the pull, each item with the version it was
+ * pulled at, so edits and links made elsewhere are kept and a conflict is named
+ * before anything is uploaded.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+
+import { appFilesDigest, readSpaceStateFile, writeSpaceStateFile } from './app-platform.js';
+import { usageError } from './errors.js';
+
+export const SPACE_LOCK_FILE = 'space-lock.json';
+export const RESOURCES_FILE = 'resources.json';
+export const SKILLS_DIR = 'skills';
+const ALIAS = /^[a-z][a-z0-9_-]{0,99}$/;
+// Links staged from a legacy App without a declared name keep the migration's `<kind>:<id>` alias until renamed
+// (`notis spaces resources name`); they can be listed and kept, never used as a Skill folder or a new entry.
+const STAGED_ALIAS = /^(database|skill|automation):[A-Za-z0-9-]{1,64}$/;
+export function isFolderAlias(alias) { return typeof alias === 'string' && ALIAS.test(alias); }
+const LINK_KINDS = new Set(['database', 'skill', 'automation']);
+const EXCLUDED_ENTRIES = new Set(['node_modules', '__pycache__', '.ds_store', '.git', '.notis', '.context']);
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function excluded(name) {
+  const lower = name.toLowerCase();
+  return EXCLUDED_ENTRIES.has(lower) || lower.startsWith('.env') || lower.endsWith('.pyc') || lower.endsWith('.pyo');
+}
+
+function safeRelativePath(value, label) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.includes('\0') || value.startsWith('/')
+    || value.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw usageError(`${label} contains an unsafe file path: ${String(value)}`);
+  }
+  return value;
+}
+
+/** Links of the three linkable kinds as the portable list `[{kind, id, alias}]`, sorted by alias. */
+export function resourceEntries(links) {
+  return (Array.isArray(links) ? links : [])
+    .filter((link) => LINK_KINDS.has(link?.kind))
+    .map((link) => ({ kind: link.kind, id: link.resource_id, alias: link.alias }))
+    .sort((a, b) => (a.alias < b.alias ? -1 : a.alias > b.alias ? 1 : 0));
+}
+
+/** The pulled list as the lock records it: identity, alias, binding and availability. */
+export function lockLinks(links) {
+  return (Array.isArray(links) ? links : [])
+    .filter((link) => LINK_KINDS.has(link?.kind))
+    .map((link) => ({ kind: link.kind, id: link.resource_id, alias: link.alias, binding_id: link.binding_id,
+      binding_revision: link.revision, available: link.available !== false }))
+    .sort((a, b) => (a.alias < b.alias ? -1 : a.alias > b.alias ? 1 : 0));
+}
+
+export function readSpaceLock(projectDir) {
+  const lock = readSpaceStateFile(projectDir, SPACE_LOCK_FILE);
+  if (lock === null) return null;
+  if (!lock || typeof lock !== 'object' || lock.version !== 1 || typeof lock.space_id !== 'string' || !Array.isArray(lock.links)
+    || !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills)) {
+    throw usageError('The Space lock file (.notis/space-lock.json) is unreadable. Pull the Space again.');
+  }
+  return lock;
+}
+
+export function writeSpaceLock(projectDir, lock) {
+  return writeSpaceStateFile(projectDir, SPACE_LOCK_FILE, lock);
+}
+
+export function readResourceList(projectDir) {
+  const path = join(resolve(projectDir), RESOURCES_FILE);
+  if (!existsSync(path)) return null;
+  if (lstatSync(path).isSymbolicLink()) throw usageError(`${RESOURCES_FILE} must be a regular file.`);
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); } catch { throw usageError(`${RESOURCES_FILE} must be valid JSON.`); }
+  if (!Array.isArray(parsed)) throw usageError(`${RESOURCES_FILE} must be a JSON array of {kind, id, alias} entries.`);
+  const seen = new Set();
+  return parsed.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).sort().join(',') !== 'alias,id,kind'
+      || !LINK_KINDS.has(entry.kind) || typeof entry.id !== 'string' || !entry.id || typeof entry.alias !== 'string'
+      || !(ALIAS.test(entry.alias) || STAGED_ALIAS.test(entry.alias))) {
+      throw usageError(`${RESOURCES_FILE}[${index}] must be {kind: database|skill|automation, id, alias} with a lowercase alias.`);
+    }
+    const key = `${entry.kind}:${entry.id}`;
+    if (seen.has(key)) throw usageError(`${RESOURCES_FILE} lists ${entry.kind} ${entry.id} twice.`);
+    seen.add(key);
+    return { kind: entry.kind, id: entry.id, alias: entry.alias };
+  });
+}
+
+export function writeResourceList(projectDir, entries) {
+  const root = resolve(projectDir);
+  const temporary = join(root, `.${RESOURCES_FILE}-${randomUUID()}`);
+  try {
+    writeFileSync(temporary, JSON.stringify(entries, null, 2) + '\n', { flag: 'wx' });
+    renameSync(temporary, join(root, RESOURCES_FILE));
+  } finally { rmSync(temporary, { force: true }); }
+}
+
+function walkSkillFolder(directory, prefix, files) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isSymbolicLink() || excluded(entry.name)) continue;
+    const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) walkSkillFolder(join(directory, entry.name), path, files);
+    else if (entry.isFile()) files[path] = readFileSync(join(directory, entry.name)).toString('base64');
+  }
+}
+
+/** Every `skills/<alias>/` folder as {alias: {files: {path: base64}, digest}}. */
+export function collectSkillFolders(projectDir) {
+  const root = join(resolve(projectDir), SKILLS_DIR);
+  const folders = {};
+  if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) return folders;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isSymbolicLink() || !entry.isDirectory()) continue;
+    if (!ALIAS.test(entry.name)) throw usageError(`${SKILLS_DIR}/${entry.name}: name the folder with the Skill alias (lowercase letters, digits, - or _).`);
+    const files = {};
+    walkSkillFolder(join(root, entry.name), '', files);
+    if (!files['SKILL.md']) throw usageError(`${SKILLS_DIR}/${entry.name} needs a SKILL.md.`);
+    folders[entry.name] = { files, digest: appFilesDigest(files) };
+  }
+  return folders;
+}
+
+/** The files of a Skill bundle a local folder keeps (the same exclusions as collectSkillFolders). */
+export function skillFolderFiles(files) {
+  return Object.fromEntries(Object.entries(files || {}).filter(([path]) => !path.split('/').some(excluded)));
+}
+
+/** Current linked Skill files own their folder; replacement requires the exact pulled snapshot. */
+export function writeSkillFolder(projectDir, alias, files, { sourceSnapshot } = {}) {
+  if (!ALIAS.test(alias)) throw usageError(`Unsafe Skill alias: ${alias}`);
+  const root = join(resolve(projectDir), SKILLS_DIR, alias);
+  const entries = Object.entries(files || {}).map(([path, encoded]) => {
+    safeRelativePath(path, `Skill ${alias}`);
+    return [path, Buffer.from(encoded, 'base64')];
+  });
+  if (sourceSnapshot !== undefined) {
+    const changed = () => usageError(`${SKILLS_DIR}/${alias} changed while pulling its current Skill. Keep these local files and pull into a new directory.`);
+    const readSnapshot = () => {
+      const current = {};
+      if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()
+        || lstatSync(dirname(root)).isSymbolicLink()) throw changed();
+      const walk = (directory, prefix = '') => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+          if (entry.isSymbolicLink() || excluded(entry.name)) throw changed();
+          const path = prefix + entry.name;
+          if (entry.isDirectory()) walk(join(directory, entry.name), path + '/');
+          else if (entry.isFile()) current[path] = readFileSync(join(directory, entry.name)).toString('base64');
+          else throw changed();
+        }
+      };
+      walk(root);
+      return current;
+    };
+    const expected = appFilesDigest(sourceSnapshot);
+    if (appFilesDigest(readSnapshot()) !== expected) throw changed();
+    if (appFilesDigest(files) === expected) return;
+    // The archive remains immutable on the server. The editable folder follows
+    // the verified linked Skill head, including normalized frontmatter/deletions.
+    const staging = join(resolve(projectDir), '.notis', `skill-pull-${randomUUID()}`);
+    const backup = `${staging}-previous`;
+    mkdirSync(staging, { recursive: true });
+    let displaced = false;
+    try {
+      for (const [path, bytes] of entries) {
+        const target = join(staging, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, bytes, { flag: 'wx' });
+      }
+      if (appFilesDigest(readSnapshot()) !== expected) throw changed();
+      renameSync(root, backup); displaced = true;
+      try { renameSync(staging, root); }
+      catch (error) { renameSync(backup, root); displaced = false; throw error; }
+      displaced = false;
+      rmSync(backup, { recursive: true });
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+      // If restoring the prior folder failed, retain its backup for recovery.
+      if (!displaced) rmSync(backup, { recursive: true, force: true });
+    }
+    return;
+  }
+  for (const [path, bytes] of entries) {
+    const target = join(root, path);
+    mkdirSync(dirname(target), { recursive: true });
+    try {
+      writeFileSync(target, bytes, { flag: 'wx' });
+    } catch (error) {
+      if (error?.code === 'EEXIST') throw usageError(`${SKILLS_DIR}/${alias}/${path} already exists in the pulled source; the Skill folder cannot be written over it.`);
+      throw error;
+    }
+  }
+}
+
+export function lockAfterPull({ spaceId, apiBase, sourceRevision, links, skills }) {
+  return { version: 1, space_id: spaceId, api_base: apiBase, source_revision: sourceRevision, pulled_at: new Date().toISOString(),
+    links: lockLinks(links), skills };
+}
+
+function byAlias(entries) {
+  return new Map(entries.map((entry) => [entry.alias, entry]));
+}
+
+/**
+ * What changed since the pull, as the server expects it:
+ * edited and new Skill folders, deleted tracked folders and list additions or
+ * removals. Returns { changes: null } when nothing changed. A deleted tracked
+ * folder removes its link even while the list still names it. Ambiguous local
+ * states (a kept folder whose list entry was removed, a renamed alias) are
+ * usage errors, not conflicts.
+ */
+export function computeSpaceSourceChanges({ lock, resources, folders, manifest }) {
+  const tracked = lock.skills || {};
+  const lockLinksByKey = new Map((lock.links || []).map((link) => [`${link.kind}:${link.id}`, link]));
+  const lockAliases = byAlias(lock.links || []);
+  const declared = new Set(Object.keys(manifest?.resources || {}));
+  const list = resources ?? resourceEntries(lock.links.map((link) => ({ ...link, resource_id: link.id })));
+  const listByKey = new Map(list.map((entry) => [`${entry.kind}:${entry.id}`, entry]));
+  const listAliases = byAlias(list);
+  const edits = {}, creations = {}, add = [], remove = [];
+  const removedSkills = new Set();
+
+  for (const [alias, folder] of Object.entries(folders)) {
+    const entry = tracked[alias];
+    if (entry) {
+      if (!listByKey.has(`skill:${entry.skill_id}`)) {
+        throw usageError(`${RESOURCES_FILE} no longer lists the Skill of ${SKILLS_DIR}/${alias}. Delete the folder too to unlink it, or keep the entry.`);
+      }
+      if (entry.folder_hash !== folder.digest) {
+        edits[alias] = { skill_id: entry.skill_id, binding_id: entry.binding_id, binding_revision: entry.binding_revision,
+          version: entry.version, files: folder.files };
+      }
+    } else if (lockAliases.has(alias) || listAliases.has(alias)) {
+      throw usageError(`${SKILLS_DIR}/${alias} matches a listed resource that is not an editable Skill folder of this pull. Choose another folder name or pull again.`);
+    } else {
+      creations[alias] = { files: folder.files };
+    }
+  }
+  for (const [alias, entry] of Object.entries(tracked)) {
+    if (folders[alias]) continue;
+    // R5: deleting a tracked folder removes its link; a list entry left behind is rewritten after the deploy.
+    if (declared.has(alias)) {
+      throw usageError(`'${alias}' is declared by this Space's definition; remove it from the definition before deleting ${SKILLS_DIR}/${alias}.`);
+    }
+    removedSkills.add(entry.skill_id);
+    remove.push({ kind: 'skill', resource_id: entry.skill_id, binding_id: entry.binding_id, binding_revision: entry.binding_revision,
+      version: entry.version });
+  }
+  for (const entry of list) {
+    const before = lockLinksByKey.get(`${entry.kind}:${entry.id}`);
+    if (!before) {
+      if (!ALIAS.test(entry.alias)) {
+        throw usageError(`${RESOURCES_FILE}: '${entry.alias}' is not a valid alias for a new link; use lowercase letters, digits, - or _.`);
+      }
+      if (lockAliases.has(entry.alias) || folders[entry.alias] || creations[entry.alias]) {
+        throw usageError(`${RESOURCES_FILE}: alias '${entry.alias}' is already used by another resource or Skill folder.`);
+      }
+      add.push({ kind: entry.kind, resource_id: entry.id, alias: entry.alias });
+    } else if (before.alias !== entry.alias) {
+      throw usageError(`${RESOURCES_FILE}: '${before.alias}' cannot be renamed to '${entry.alias}' here; aliases are stable once linked.`);
+    }
+  }
+  for (const link of lock.links || []) {
+    if (listByKey.has(`${link.kind}:${link.id}`) || removedSkills.has(link.id)) continue;
+    if (declared.has(link.alias)) {
+      throw usageError(`'${link.alias}' is declared by this Space's definition; remove it from the definition before removing it from ${RESOURCES_FILE}.`);
+    }
+    remove.push({ kind: link.kind, resource_id: link.id, binding_id: link.binding_id, binding_revision: link.binding_revision });
+  }
+  const changes = {};
+  if (Object.keys(edits).length || Object.keys(creations).length) {
+    changes.skills = { ...(Object.keys(edits).length ? { edits } : {}), ...(Object.keys(creations).length ? { creations } : {}) };
+  }
+  if (add.length || remove.length) changes.links = { ...(add.length ? { add } : {}), ...(remove.length ? { remove } : {}) };
+  if (!Object.keys(changes).length) return { changes: null, summary: null, fingerprint: null };
+  const summary = { skills: { edited: Object.keys(edits).sort(), created: Object.keys(creations).sort() },
+    links: { added: add.map((entry) => `${entry.alias} (${entry.kind})`), removed: remove.map((entry) => `${entry.kind} ${entry.resource_id}`) } };
+  return { changes, summary, fingerprint: createHash('sha256').update(stableJson(changes)).digest('hex') };
+}
+
+/**
+ * The lock and list after a publication: the applied Skill versions, the new
+ * Skills' identities and the Space's current links (including links made
+ * elsewhere since the pull, which the deploy kept).
+ */
+export function applyPublication({ lock, folders, result }) {
+  const applied = result?.applied;
+  const next = { ...lock, source_revision: result?.published_revision ?? lock.source_revision, updated_at: new Date().toISOString() };
+  if (!applied) return { lock: next, resources: null };
+  const skills = {};
+  for (const [alias, folder] of Object.entries(folders)) {
+    const change = applied.skills?.[alias];
+    if (change) {
+      skills[alias] = { skill_id: change.skill_id, binding_id: change.binding_id, binding_revision: change.binding_revision,
+        version: change.version, folder_hash: folder.digest };
+    } else if (lock.skills?.[alias]) {
+      skills[alias] = lock.skills[alias];
+    }
+  }
+  next.skills = skills;
+  next.links = lockLinks(applied.space_links || []);
+  return { lock: next, resources: resourceEntries(applied.space_links || []) };
+}
+
+/** One line describing what a deploy changed, with the review link of every changed Skill. */
+export function describeAppliedChanges(result) {
+  const applied = result?.applied;
+  if (!applied) return '';
+  const parts = [];
+  const edited = Object.entries(applied.skills || {}).filter(([, change]) => change.operation === 'update').map(([alias]) => alias);
+  const created = Object.entries(applied.skills || {}).filter(([, change]) => change.operation === 'create').map(([alias]) => alias);
+  if (edited.length) parts.push(`Skills updated: ${edited.join(', ')}`);
+  if (created.length) parts.push(`Skills created: ${created.join(', ')}`);
+  const added = (applied.links || []).flatMap((link) => (link.added || []).map((entry) => `${entry.alias} (${link.kind})`));
+  const removed = (applied.links || []).flatMap((link) => (link.removed || []).map((entry) => `${entry.alias} (${link.kind})`));
+  if (added.length) parts.push(`Links added: ${added.join(', ')}`);
+  if (removed.length) parts.push(`Links removed: ${removed.join(', ')}`);
+  for (const review of result.reviews || []) {
+    if (review.review_url) parts.push(`Review ${review.alias}: ${review.review_url}`);
+  }
+  return parts.length ? ` ${parts.join('. ')}.` : '';
+}