@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/packages/programs.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * IC-018 program declarations: check executable contributions on open points at supported versions,
+ * their declared programs, and each declaration's launch shape. This module never spawns a process.
+ * `launchSpec` builds the shell-free spec that the D.3 launcher uses, with arguments, cwd, and
+ * environment supplied by core.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { isLocalId } = require('../../helper/package-ids.js');
+const { SEGMENT, SEGMENT_GRAMMAR } = require('./digest.js');
+
+const ARGV_SHAPES                                              = Object.freeze({
+  worker: Object.freeze(['worker-recipe']),
+  'capability-provider': Object.freeze(['capability-cli']),
+});
+const BINARY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PROGRAM_KEYS = ['id', 'binary', 'path', 'argv'];
+const platform = require('node:process').platform;
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Validate IC-018 program declarations and each executable contribution's program references. */
+function programFindings(
+  manifest     ,
+  { root = null, pointsRegistry, fsImpl = fs, packageId = null }     ,
+)        {
+  const findings        = [];
+  const add = (field        , code        , message        , allowed     ) =>
+    findings.push({ package: packageId, field, code, severity: 'error', message, allowed });
+  const contributions = Array.isArray(manifest?.contributions) ? manifest.contributions : [];
+  const executable = contributions
+    .map((entry     , index        ) => ({ entry, index, point: pointsRegistry.points.find((item     ) => item.id === entry?.point) }))
+    .filter((item     ) => item.point?.tier === 'executable'
+      && item.point.status === 'open'
+      && item.point.versions.includes(item.entry?.version));
+
+  if (executable.length === 0) return findings;
+
+  function isCliCapability(entry     , point     )          {
+    if (point?.id !== 'capability-provider') return false;
+    if (Array.isArray(entry?.programs) && entry.programs.length > 0) return true;
+    if (!root || !entry?.file || typeof entry.file !== 'string') return false;
+    try {
+      const real = path.join(root, entry.file);
+      const text = fsImpl.readFileSync(real, 'utf8');
+      const parsed = JSON.parse(text);
+      return parsed?.kind === 'cli';
+    } catch {
+      return false;
+    }
+  }
+
+  const needsPrograms = executable.some(({ entry, point }     ) => {
+    if (point?.id === 'capability-provider') {
+      return isCliCapability(entry, point);
+    }
+    return true;
+  });
+
+  const rawPrograms = manifest?.programs;
+  if (rawPrograms === undefined) {
+    if (needsPrograms) {
+      add('programs', 'program-invalid', 'programs must be an array of at most 16 declarations', 'an array of 0 to 16 program declarations');
+    }
+  } else if (!Array.isArray(rawPrograms) || rawPrograms.length > 16) {
+    add('programs', 'program-invalid', 'programs must be an array of at most 16 declarations', 'an array of 0 to 16 program declarations');
+  }
+
+  const declarations = Array.isArray(rawPrograms) ? rawPrograms : [];
+  const declaredIds = new Set        ();
+  const seenIds = new Set        ();
+  declarations.forEach((program     , index        ) => {
+    const field = `programs[${index}]`;
+    if (!isObject(program)) {
+      add(field, 'program-invalid', 'a program declaration must be an object', 'an object with id, binary or path, and argv');
+      return;
+    }
+    for (const key of Object.keys(program)) {
+      if (!PROGRAM_KEYS.includes(key)) add(`${field}.${key}`, 'program-invalid', `'${key}' is not a program declaration field`, PROGRAM_KEYS);
+    }
+
+    const validId = isLocalId(program.id);
+    if (!validId) {
+      add(`${field}.id`, 'program-invalid', 'program id must be a local id', 'a local id');
+    } else if (seenIds.has(program.id)) {
+      add(`${field}.id`, 'program-invalid', `program id '${program.id}' is declared more than once`, 'a unique local id');
+    } else {
+      seenIds.add(program.id);
+      declaredIds.add(program.id);
+    }
+
+    const hasBinary = Object.hasOwn(program, 'binary');
+    const hasPath = Object.hasOwn(program, 'path');
+    if (hasBinary === hasPath) {
+      add(field, 'program-invalid', 'exactly one of binary or path is required', ['binary', 'path']);
+    } else if (hasBinary) {
+      if (typeof program.binary !== 'string' || program.binary.length > 64 || !BINARY.test(program.binary)) {
+        add(`${field}.binary`, 'program-invalid', 'binary must be a bare executable name of at most 64 characters', '^[A-Za-z0-9][A-Za-z0-9._-]*$ (at most 64 characters)');
+      }
+    } else {
+      validateProgramPath(program.path, `${field}.path`);
+    }
+  });
+
+  for (const { entry, index, point } of executable) {
+    const field = `contributions[${index}].programs`;
+    const refs = entry?.programs;
+    if (!Array.isArray(refs) || refs.length === 0) {
+      if (point?.id === 'capability-provider' && !isCliCapability(entry, point)) {
+        continue;
+      }
+      add(field, 'program-undeclared', 'an executable contribution must name every program it launches', [...declaredIds]);
+      continue;
+    }
+    refs.forEach((id     ) => {
+      if (typeof id !== 'string' || !declaredIds.has(id)) {
+        add(field, 'program-undeclared', `program '${String(id)}' is not declared`, [...declaredIds]);
+      }
+    });
+  }
+
+  declarations.forEach((program     , index        ) => {
+    if (!isObject(program)) return;
+    const field = `programs[${index}].argv`;
+    const usingPoints = executable.filter(({ entry }     ) =>
+      Array.isArray(entry?.programs) && entry.programs.includes(program.id));
+    let allowed          ;
+    if (usingPoints.length > 0) {
+      const shapes = usingPoints.map(({ point }     ) => ARGV_SHAPES[point.id] ?? []);
+      allowed = shapes.length === 0 ? [] : [...shapes[0]].filter((shape) => shapes.every((list                   ) => list.includes(shape)));
+    } else {
+      allowed = [...new Set        (executable.flatMap(({ point }     ) => [...(ARGV_SHAPES[point.id] ?? [])]))];
+    }
+    if (typeof program.argv !== 'string' || !allowed.includes(program.argv)) {
+      add(field, 'program-invalid', 'argv must name a shape defined by the executable point using this program', allowed);
+    }
+  });
+
+  return findings;
+
+  function validateProgramPath(rel     , field        )       {
+    const limits = pointsRegistry.limits;
+    if (typeof rel !== 'string' || rel.length === 0) {
+      add(field, 'program-invalid', 'path must be a non-empty POSIX package-relative path', 'a package-relative path to an executable regular file');
+      return;
+    }
+    if (rel.startsWith('/') || rel.split('/').includes('..')) {
+      add(field, 'path-escapes-root', `${rel} leaves the package root`, 'a path inside the package root');
+      return;
+    }
+    if (rel.length > limits.pathLength || rel.split('/').some((segment        ) => !SEGMENT.test(segment))) {
+      add(field, 'program-invalid', `${rel} breaks the package path rules`, `${SEGMENT_GRAMMAR} per segment, at most ${limits.pathLength} characters`);
+      return;
+    }
+    if (!root) return;
+
+    let rootReal        ;
+    let real        ;
+    try {
+      rootReal = fsImpl.realpathSync(root);
+      real = fsImpl.realpathSync(path.join(root, rel));
+    } catch (error     ) {
+      add(field, 'file-missing', `${rel} does not exist: ${error?.message || String(error)}`, 'an existing regular file');
+      return;
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) {
+      add(field, 'path-escapes-root', `${rel} resolves outside the package root`, 'a path inside the package root');
+      return;
+    }
+    let stat     ;
+    try {
+      stat = fsImpl.statSync(real);
+    } catch (error     ) {
+      add(field, 'file-missing', `${rel} cannot be read: ${error?.message || String(error)}`, 'an existing regular file');
+      return;
+    }
+    if (!stat.isFile()) {
+      add(field, 'program-invalid', `${rel} is not a regular file`, 'an executable regular file');
+      return;
+    }
+    if (platform !== 'win32' && (stat.mode & 0o111) === 0) {
+      add(field, 'program-invalid', `${rel} has no execute bit`, 'a file with at least one execute bit');
+    }
+  }
+}
+
+/** Build a shell-free launch description using only the declared executable and core-provided arguments. */
+function launchSpec({ program, storeEntry, recipeArgv, cwd, env }     )      {
+  if (!Array.isArray(recipeArgv) || recipeArgv.some((arg     ) => typeof arg !== 'string')) {
+    throw new TypeError('recipeArgv must be an array of strings');
+  }
+  let file        ;
+  if (typeof program?.binary === 'string') {
+    file = program.binary;
+  } else if (typeof program?.path === 'string') {
+    const root = path.resolve(storeEntry);
+    file = path.resolve(root, program.path);
+    if (file !== root && !file.startsWith(root + path.sep)) {
+      throw new Error('program path leaves the store entry');
+    }
+  } else {
+    throw new TypeError('program must declare a binary or path');
+  }
+  return {
+    file,
+    args: [...recipeArgv],
+    options: { shell: false, cwd, env, windowsHide: true },
+  };
+}
+
+module.exports = { ARGV_SHAPES, programFindings, launchSpec };

package/src/runtime/packages/scaffold.js

@@ -0,0 +1,277 @@
+'use strict';
+
+// IC-025: authored source lives under package/, never in an install ledger or package store.
+// .staging- siblings older than 24 hours are removed by the scaffold itself.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { randomBytes } = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { isPackageId, isReservedPackageId, isLocalId, qualifiedId, projectedName } = require('../../helper/package-ids.js');
+const { parseSemVer } = require('../../helper/semver.js');
+const { loadPoints, templateFindings, POINTS_FILE } = require('./points.js');
+const { checkPackage, MANIFEST_FILE } = require('./manifest.js');
+const { detectedProjectRoot } = require('./grants.js');
+const { hostVersion } = require('./view.js');
+const { packagePaths } = require('./store.js');
+const { configHome } = require('../config-home.js');
+const { readLock, lockPackages } = require('../../state/lockfile.js');
+const { SEGMENT } = require('./digest.js');
+
+const TIERS = ['inert', 'instruction', 'executable'];
+const STAGING = /^\.staging-[a-z0-9-]+-[0-9a-f]{8}$/;
+const DAY = 24 * 3600000;
+
+function stat(file        , fsImpl     )      {
+  try { return fsImpl.lstatSync(file); }
+  catch (error     ) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+/** Resolve existing ancestors, retaining the not-yet-created suffix. A dangling link refuses resolution. */
+function realTarget(file        , fsImpl     )         {
+  const absolute = path.resolve(file);
+  if (stat(absolute, fsImpl)) return fsImpl.realpathSync(absolute);
+  const parent = path.dirname(absolute);
+  if (parent === absolute) throw new Error(`cannot resolve ${absolute}`);
+  return path.join(realTarget(parent, fsImpl), path.basename(absolute));
+}
+
+function within(file        , root        )          {
+  const relative = path.relative(root, file);
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+const commandArg = (value        )         =>
+  /^[A-Za-z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+
+function nextSteps(id        , dir        , tierMax        , grantsPath               )        {
+  const target = commandArg(dir);
+  const next = [
+    { step: 'edit', command: null, note: `write the content of the listed stub files and the README's "What and why"; edit only files under ${dir}; from /do, this is /do-implement standalone with task id package-${id}` },
+    { step: 'check', command: `doflow package --action check --path ${target}`, note: 'repeat until clean' },
+    { step: 'add', command: `doflow package --action add --source ${target}`, note: 'writes a plan only; shows the inventory, the projection bytes and the grant lines' },
+    { step: 'apply', command: 'doflow package --action add --plan <planId>', note: "installing a package is on the person's ask-first list; ask before running it, and in a headless run stop here and print this line" },
+    { step: 'enable', command: `doflow package --action enable --id ${id}`, note: 'an inert package is then active' },
+  ];
+  if (tierMax !== 'inert') {
+    next.push({
+      step: 'trust', command: `doflow package --action trust --id ${id}`,
+      note: grantsPath === null
+        ? 'there is no config home, so no grant can exist; never append a trust line from a model session'
+        : `prints the line a person appends to ${grantsPath}; never append it from a model session`,
+    });
+  }
+  next.push({
+    step: 'iterate', command: null,
+    note: `edit, check, update --id ${id}, update --plan <planId>; above inert, every applied change of content needs a new trust line; DoFlow does not follow the folder`,
+  });
+  return next;
+}
+
+function ignoredByGit(target        , fsImpl     , env     )                 {
+  const parent = path.dirname(target);
+  let found = false;
+  for (let dir = parent; ; dir = path.dirname(dir)) {
+    try { if (stat(path.join(dir, '.git'), fsImpl)) { found = true; break; } } catch { return null; }
+    if (path.dirname(dir) === dir) break;
+  }
+  if (!found) return null;
+  try {
+    const result = spawnSync('git', ['check-ignore', '-q', target], {
+      shell: false, cwd: parent, env, encoding: 'utf8', timeout: 4000,
+    });
+    return result.status === 0 ? true : result.status === 1 ? false : null;
+  } catch { return null; }
+}
+
+/** Create only the authored tree and its staging sibling; rendering and telemetry belong to command.ts. */
+function scaffoldPackage({
+  id, points, dir, cwd = process.cwd(), homeDir = os.homedir(), env = process.env,
+  repoRoot = REPO_ROOT, now = Date.now(), fsImpl = fs, grantsPath = null,
+}      = {})      {
+  const finding = (field        , code        , message        , allowed     , severity = 'error')      =>
+    ({ package: typeof id === 'string' ? id : null, field, code, severity, message, allowed });
+  const refuse = (code        , field        , message        , allowed     , findings        = [])      =>
+    ({ ok: false, error: code, findings: [finding(field, code, message, allowed), ...findings] });
+
+  let staging                = null;
+  try {
+    const loaded = loadPoints({ repoRoot, fsImpl });
+    if (!loaded.ok) {
+      // The loader requires template keys. Preserve new's more specific refusal for an absent key.
+      try {
+        const raw = JSON.parse(fsImpl.readFileSync(path.join(repoRoot, POINTS_FILE), 'utf8'));
+        const requested = typeof points === 'string' ? points.split(',').map((s        ) => s.split(':')[0]) : [];
+        const missing = raw.points?.find((p     ) => requested.includes(p.id) && p.status === 'open' && !p.template);
+        if (missing) return refuse('template-missing', 'points', `point '${missing.id}' names no template`, 'an open point with a template');
+      } catch { /* report the registry errors below */ }
+      return refuse('state-unreadable', 'points', loaded.errors.join('; '), 'a valid point registry');
+    }
+    const registry = loaded.registry;
+    const open = registry.points.filter((p     ) => p.status === 'open');
+    const available = open.filter((p     ) => p.template).map((p     ) => p.id);
+    const usage = (message        )      => ({
+      ...refuse('usage', 'arguments', `${message}; open points with templates: ${available.join(', ')}`, available),
+      usage: true,
+    });
+    if (typeof id !== 'string' || id.length === 0) return usage('new requires --id <id>');
+    if (typeof points !== 'string' || points.length === 0) return usage('new requires --points <point[:local],...>');
+    if (!isPackageId(id)) return refuse('bad-id', 'id', `package id '${id}' breaks the grammar`, 'an IC-003 package id');
+    if (isReservedPackageId(id)) return refuse('reserved-id', 'id', `package id '${id}' is reserved`, 'an unreserved package id');
+    if (dir !== undefined && (typeof dir !== 'string' || dir.length === 0)) return usage('--dir takes a non-empty path');
+
+    const entries = points.split(',');
+    if (entries.length > 64) return refuse('bad-type', 'points', '--points accepts at most 64 entries', '1 to 64 entries');
+    const selected        = [];
+    const seen = new Set        ();
+    for (const entry of entries) {
+      const parts = entry.split(':');
+      const point = registry.points.find((p     ) => p.id === parts[0]);
+      if (!point) return refuse('undeclared-point', 'points', `point '${parts[0]}' is not declared; open points: ${open.map((p     ) => p.id).join(', ')}`, open.map((p     ) => p.id));
+      if (point.status !== 'open') return refuse('point-reserved', 'points', `point '${point.id}' is reserved and opens with ${point.opensWith}`, available);
+      const local = parts.length === 1 ? (isLocalId(point.id) ? point.id : 'provider') : parts[1];
+      if (parts.length > 2 || !isLocalId(local) || !qualifiedId(id, local)) return refuse('bad-id', 'points', `invalid local id in '${entry}'`, 'point[:local] with an IC-003 local id');
+      const key = `${point.id}:${local}`;
+      if (seen.has(key)) return refuse('bad-id', 'points', `duplicate contribution '${key}'`, 'unique (point, local id) pairs');
+      seen.add(key);
+      if (!point.template) return refuse('template-missing', 'points', `point '${point.id}' names no template`, available);
+      selected.push({ point, local, version: Math.max(...point.versions) });
+    }
+
+    const projectRoot = detectedProjectRoot({ cwd, homeDir, fsImpl });
+    if (dir === undefined && projectRoot === null) return usage('no project root was detected; supply --dir <path>');
+    const target = dir === undefined ? path.join(projectRoot, '.doflow', 'package', id) : path.resolve(cwd, dir);
+    let real        ;
+    const forbidden = ()          => {
+      real = realTarget(target, fsImpl);
+      const config = configHome(env).dir;
+      const roots = [packagePaths(homeDir).base, repoRoot, REPO_ROOT, ...(config === null ? [] : [config])];
+      return roots.some((root        ) => within(real, realTarget(root, fsImpl)))
+        || `${real}${path.sep}`.includes(`${path.sep}.doflow${path.sep}state${path.sep}`);
+    };
+    try {
+      if (forbidden()) return refuse('target-forbidden', 'dir', `target is inside protected storage: ${target}`, 'an authored source directory outside protected storage');
+    } catch (error     ) {
+      return refuse('target-forbidden', 'dir', `cannot resolve target safely: ${error.message}`, 'a resolvable target');
+    }
+    const originalReal = real ;
+    const nonempty = ()          => {
+      const info = stat(target, fsImpl);
+      return !!info && (!info.isDirectory() || info.isSymbolicLink() || fsImpl.readdirSync(target).length !== 0);
+    };
+    if (nonempty()) return refuse('target-not-empty', 'dir', `target is not an empty directory: ${target}`, 'a missing or empty directory');
+
+    const defects = templateFindings({
+      registry: { ...registry, points: selected.map((s     ) => s.point) }, repoRoot, fsImpl,
+    });
+    if (defects.length > 0) return refuse('template-invalid', 'templates', 'the selected templates are invalid', 'valid core templates', defects);
+    const host = hostVersion(repoRoot);
+    const parsed = typeof host === 'string' ? parseSemVer(host) : null;
+    if (!parsed) return refuse('host-incompatible', 'doflow', 'the running DoFlow version cannot be read', 'a running semver version');
+
+    const warnings        = [];
+    const rows = lockPackages(readLock({ scope: 'global', homeDir }, { fsImpl }));
+    if (rows.some((row     ) => row.id === id)) warnings.push(finding('id', 'collision-package', `package '${id}' is already recorded`, 'use update to apply edited source', 'warning'));
+
+    const tierMax = selected.reduce((top        , s     ) => TIERS.indexOf(s.point.tier) > TIERS.indexOf(top) ? s.point.tier : top, 'inert');
+    const next = nextSteps(id, target, tierMax, grantsPath);
+    const substitutions = (local        )                         => ({
+      package: id, local, qualified: qualifiedId(id, local) ?? '', projected: projectedName(qualifiedId(id, local) ?? '') ?? '',
+      version: '0.1.0', host,
+    });
+    const replace = (text        , values                        )         => {
+      const result = text.replace(/\{\{([^{}]*)\}\}/g, (match        , name        ) => {
+        if (!Object.hasOwn(values, name)) throw new Error(`unknown template placeholder ${match}`);
+        return values[name];
+      });
+      if (result.includes('{{')) throw new Error('unclosed template placeholder');
+      return result;
+    };
+    const files = new Map                                        ();
+    const put = (relative        , text        , mode = 0o644)       => {
+      if (relative.includes('\\') || relative.split('/').some((part        ) => !SEGMENT.test(part))
+        || relative.length > registry.limits.pathLength) throw new Error(`invalid template output path ${relative}`);
+      if (files.has(relative)) throw new Error(`templates write the same file: ${relative}`);
+      files.set(relative, { text, mode });
+    };
+    const programs        = [];
+    const contributions        = [];
+    const inventory        = [];
+    for (const { point, local, version } of selected) {
+      const base = path.join(repoRoot, 'core', 'registry', point.template);
+      const values = substitutions(local);
+      const template = JSON.parse(replace(fsImpl.readFileSync(path.join(base, 'template.json'), 'utf8'), values));
+      const contribution      = { point: point.id, version, id: local, [point.entry]: template.path };
+      if (point.tier === 'executable') {
+        programs.push(...template.programs);
+        contribution.programs = template.programs.map((p     ) => p.id);
+      }
+      contributions.push(contribution);
+      inventory.push({ point: point.id, version, qualifiedId: qualifiedId(id, local), tier: point.tier, [point.entry]: template.path });
+      const copy = (source        , relative = '')       => {
+        for (const name of fsImpl.readdirSync(source).sort()) {
+          const abs = path.join(source, name);
+          const info = fsImpl.lstatSync(abs);
+          const rel = relative ? `${relative}/${name}` : name;
+          if (info.isSymbolicLink()) throw new Error(`template symlink: ${abs}`);
+          if (info.isDirectory()) copy(abs, rel);
+          else if (info.isFile()) put(
+            point.entry === 'file' ? template.path : `${template.path}/${replace(rel, values)}`,
+            replace(fsImpl.readFileSync(abs, 'utf8'), values), info.mode & 0o111 ? 0o755 : 0o644,
+          );
+          else throw new Error(`template special file: ${abs}`);
+        }
+      };
+      copy(path.join(base, 'files'));
+    }
+    const manifest = {
+      manifest: 1, id, version: '0.1.0', doflow: `>=${host} <${BigInt(parsed.major) + 1n}.0.0`,
+      ...(programs.length ? { programs } : {}), contributions,
+    };
+    put(MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`);
+    put('README.md', replace(fsImpl.readFileSync(path.join(repoRoot, 'core', 'registry', 'package-templates', 'README.md'), 'utf8'), {
+      ...substitutions(id),
+      contributions: inventory.map((c     ) => `- ${c.point} ${c.qualifiedId} ${c.tier} ${c.file ?? c.dir}`).join('\n'),
+      next: next.map((n     ) => `${n.step}: ${n.command ? `${n.command}; ` : ''}${n.note}`).join('\n'),
+    }));
+
+    const parent = path.dirname(target);
+    fsImpl.mkdirSync(parent, { recursive: true });
+    for (const name of fsImpl.readdirSync(parent)) {
+      const sibling = path.join(parent, name);
+      if (!STAGING.test(name) || sibling === target) continue;
+      const info = fsImpl.lstatSync(sibling);
+      if (info.isDirectory() && !info.isSymbolicLink() && now - info.mtimeMs > DAY) fsImpl.rmSync(sibling, { recursive: true, force: true });
+    }
+    staging = path.join(parent, `.staging-${id}-${randomBytes(4).toString('hex')}`);
+    fsImpl.mkdirSync(staging);
+    for (const [relative, file] of files) {
+      const output = path.join(staging, ...relative.split('/'));
+      fsImpl.mkdirSync(path.dirname(output), { recursive: true });
+      fsImpl.writeFileSync(output, file.text, { flag: 'wx', mode: file.mode });
+    }
+    const checked = checkPackage(staging, { repoRoot, pointsRegistry: registry, hostVersion: host, bundled: [], fsImpl });
+    if (!checked.ok) return refuse('template-invalid', 'templates', 'the staged scaffold failed package check', 'a clean staged package', checked.findings);
+    if (forbidden() || real  !== originalReal) return refuse('target-forbidden', 'dir', 'target ancestry changed during scaffolding', 'the original safe target');
+    if (nonempty()) return refuse('target-not-empty', 'dir', `target became non-empty: ${target}`, 'a missing or empty directory');
+    if (stat(target, fsImpl)) fsImpl.rmdirSync(target);
+    try { fsImpl.renameSync(staging, target); }
+    catch (error     ) {
+      if (['EEXIST', 'ENOTEMPTY'].includes(error.code)) return refuse('target-not-empty', 'dir', `target became non-empty: ${target}`, 'a missing or empty directory');
+      throw error;
+    }
+    staging = null;
+    return {
+      ok: true, id, dir: target, files: [...files.keys()].sort(), contributions: inventory, tierMax,
+      contentDigest: checked.contentDigest, capabilityDigest: checked.capabilityDigest,
+      ignoredByGit: ignoredByGit(target, fsImpl, env), findings: [...warnings, ...checked.findings], next,
+    };
+  } catch (error     ) {
+    return refuse('template-invalid', 'templates', error.message || String(error), 'a readable, valid scaffold template and writable target');
+  } finally {
+    if (staging !== null) fsImpl.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+module.exports = { scaffoldPackage };

package/src/runtime/packages/source.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Parse package source specs for IC-022: local paths, git URLs and npm names.
+ * Unsupported schemes and URL credentials are refused as `bad-type`. This module
+ * dispatches git and pinned npm fetches through `fetch.ts`; the caller supplies the staging directory.
+ */
+
+const { pinGit, fetchGit, pinNpm, fetchNpm } = require('./fetch.js');
+
+                   
+                                                            
+                                                   
+                                                                    
+                                                                                     
+
+const ALLOWED = 'a local path, git:https://<host>/<repo>[#<subdir>]@<ref>, or npm:<name>@<version or range>';
+
+function badType(message        )              {
+  return {
+    ok: false,
+    finding: { package: null, field: 'source', code: 'bad-type', severity: 'error', message, allowed: ALLOWED },
+  };
+}
+
+const hasControl = (value        )          => /[\u0000-\u001f\u007f]/u.test(value);
+const hasSpaceOrControl = (value        )          => /[\s\u0000-\u001f\u007f]/u.test(value);
+
+function parseSource(spec        )              {
+  if (spec.startsWith('git:')) {
+    const body = spec.slice(4);
+    const refAt = body.lastIndexOf('@');
+    if (refAt < 0) return badType('git source needs a non-empty ref after the final @');
+    const target = body.slice(0, refAt);
+    const ref = body.slice(refAt + 1);
+    const hashAt = target.indexOf('#');
+    const url = hashAt < 0 ? target : target.slice(0, hashAt);
+    const subdir = hashAt < 0 ? undefined : target.slice(hashAt + 1);
+    if (!url || url.length > 512 || hasSpaceOrControl(url)) return badType('git URL must be non-empty, at most 512 characters, and contain no whitespace or control characters');
+    if (!ref || ref.length > 512 || hasSpaceOrControl(ref) || ref.startsWith('-')) return badType('git ref must be non-empty, at most 512 characters, and contain no whitespace or control characters');
+    let parsed                          ;
+    try { parsed = new URL(url); } catch { return badType('git URL must be a valid https URL'); }
+    if (parsed.protocol !== 'https:' || !parsed.host) return badType('git URL must use https and include a host');
+    if (parsed.username || parsed.password) return badType('git URL must not contain credentials');
+    if (subdir !== undefined && (!subdir || subdir.startsWith('/') || subdir.startsWith('-') || subdir.includes('\\') || subdir.split('/').includes('..'))) {
+      return badType('git subdir must be non-empty, relative, and contain no .. segment or backslash');
+    }
+    return { ok: true, source: { type: 'git', url, ref, ...(subdir === undefined ? {} : { path: subdir }) } };
+  }
+  if (spec.startsWith('npm:')) {
+    const body = spec.slice(4);
+    const versionAt = body.lastIndexOf('@');
+    if (versionAt <= 0) return badType('npm source needs a package name and non-empty version or range');
+    const name = body.slice(0, versionAt);
+    const version = body.slice(versionAt + 1);
+    if (name.startsWith('-') || name.length > 214 || !/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name)) {
+      return badType('npm package name does not match the allowed package name grammar');
+    }
+    if (!version || version.length > 512 || hasControl(version)) return badType('npm version or range must be non-empty, at most 512 characters, and contain no control characters');
+    return { ok: true, source: { type: 'npm', name, version } };
+  }
+  if (/^[A-Za-z][A-Za-z0-9+.-]+:/.test(spec)) return badType('source scheme is not supported');
+  return { ok: true, source: { type: 'local', path: spec } };
+}
+
+function fetchGrantLine(source              , at        )         {
+  return JSON.stringify({ grant: 'fetch', source, at });
+}
+
+function pinSource(source     , opts     )      {
+  if (source?.type === 'git') return pinGit(source, opts);
+  if (source?.type === 'npm') return pinNpm(source, opts);
+  const message = 'source cannot be pinned';
+  return {
+    ok: false,
+    finding: { package: null, field: 'source', code: 'bad-type', severity: 'error', message, allowed: ALLOWED },
+  };
+}
+
+function fetchSource(pinned     , opts     )      {
+  if (pinned?.type === 'git') return fetchGit(pinned, opts);
+  if (pinned?.type === 'npm') return fetchNpm(pinned, opts);
+  const message = 'source cannot be fetched';
+  return {
+    ok: false,
+    findings: [{ package: null, field: 'source', code: 'bad-type', severity: 'error', message, allowed: ALLOWED }],
+  };
+}
+
+module.exports = { parseSource, fetchGrantLine, pinSource, fetchSource };