@mnstry/atelier 0.2.0-alpha.1

package/src/commands/distribution.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// atelier distribution check — verifies that a distribution package carries
+// the required MNSTRY attribution markers. The normative attribution policy
+// lives in TRADEMARKS.md under "Required attribution"; this command checks
+// only the mechanical markers and points there rather than restating policy.
+//
+// Exit codes: 0 = checks passed, 1 = blocking attribution check failed,
+// 2 = usage error (unknown subcommand or unusable target).
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseArgs } from '../project/config.mjs'
+
+const ATTRIBUTION_BYTES = 'powered by MNSTRY Atelier'
+const ATTRIBUTION_EXT_KEY = 'mnstry.atelier/attribution'
+const PACK_MANIFEST_NAME = 'atelier.pack.json'
+const PREFIX = '[atelier-distribution:check]'
+const POLICY_POINTER = 'see TRADEMARKS.md ("Required attribution") and docs/attestation.md'
+
+const log = (message) => console.log(`${PREFIX} ${message}`)
+const logError = (message) => console.error(`${PREFIX} ${message}`)
+
+// Paths in output stay relative to the checked distribution so logs never
+// leak machine-local absolute paths.
+const displayPath = (target, file) => path.relative(target, file) || path.basename(file)
+
+function checkReadmeAttribution(target) {
+  const readmePath = path.join(target, 'README.md')
+  let bytes
+  try {
+    bytes = fs.readFileSync(readmePath)
+  } catch {
+    return { ok: false, reason: 'README.md is missing from the distribution root' }
+  }
+  if (!bytes.includes(ATTRIBUTION_BYTES)) {
+    return { ok: false, reason: `README.md does not contain the exact byte string "${ATTRIBUTION_BYTES}"` }
+  }
+  return { ok: true }
+}
+
+function manifestIn(dir) {
+  const file = path.join(dir, PACK_MANIFEST_NAME)
+  return fs.existsSync(file) ? file : null
+}
+
+function findPackManifests(target, packOverride) {
+  if (typeof packOverride === 'string' && packOverride.trim()) {
+    const resolved = path.resolve(packOverride)
+    let stat = null
+    try {
+      stat = fs.statSync(resolved)
+    } catch {
+      return { manifests: [], note: `--pack path does not exist: ${packOverride}` }
+    }
+    if (stat.isDirectory()) {
+      const manifest = manifestIn(resolved)
+      if (manifest) return { manifests: [manifest], note: null }
+      return { manifests: [], note: `--pack directory has no ${PACK_MANIFEST_NAME}: ${packOverride}` }
+    }
+    return { manifests: [resolved], note: null }
+  }
+
+  const packsRoot = path.join(target, 'packs')
+  let entries = []
+  try {
+    entries = fs.readdirSync(packsRoot, { withFileTypes: true })
+  } catch {
+    return { manifests: [], note: `no packs/ directory found; nothing to check for the pack-manifest attribution key` }
+  }
+  const manifests = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => manifestIn(path.join(packsRoot, entry.name)))
+    .filter(Boolean)
+  if (!manifests.length) {
+    return { manifests: [], note: `no ${PACK_MANIFEST_NAME} found under packs/` }
+  }
+  return { manifests, note: null }
+}
+
+// Advisory only: reported, never blocking, regardless of what it finds.
+function reportPackAttribution(target, packOverride) {
+  const { manifests, note } = findPackManifests(target, packOverride)
+  if (note) log(`advisory: ${note}`)
+  for (const manifest of manifests) {
+    const shown = displayPath(target, manifest)
+    let doc
+    try {
+      doc = JSON.parse(fs.readFileSync(manifest, 'utf8'))
+    } catch {
+      log(`advisory: ${shown} is not readable JSON; attribution key not verified`)
+      continue
+    }
+    if (doc?.ext?.[ATTRIBUTION_EXT_KEY] === ATTRIBUTION_BYTES) {
+      log(`advisory: ${shown} declares ext["${ATTRIBUTION_EXT_KEY}"] — satisfied`)
+    } else {
+      log(`advisory: ${shown} does not declare ext["${ATTRIBUTION_EXT_KEY}"] — ${POLICY_POINTER}`)
+    }
+  }
+}
+
+// Blocking CLI probe. runCli accepts injected stdout/stderr writers, so a
+// wrapper can swallow the attribution that help/version output carries. The
+// probe therefore spawns the distribution's own declared bin with --version
+// through real pipes (not the wrapper's writers) and requires the exact
+// attribution byte string in the child's stdout.
+//
+// The probe is opt-out-proof for anything that looks like a distribution:
+// a target that depends on @mnstry/atelier, ships packs/, or carries an
+// atelier.project.json MUST declare a probe-able bin — a missing or empty
+// bin, or a package.json that does not parse, is a blocking failure there.
+// Only a target with none of those markers gets the advisory skip (packages
+// without a CLI exist). A declared bin that cannot be resolved, or whose
+// --version stdout lacks the attribution bytes, is always blocking.
+function looksLikeDistribution(target, pkg) {
+  if (pkg && (pkg.dependencies?.['@mnstry/atelier'] || pkg.peerDependencies?.['@mnstry/atelier'] || pkg.devDependencies?.['@mnstry/atelier'])) return true
+  if (fs.existsSync(path.join(target, 'packs'))) return true
+  if (fs.existsSync(path.join(target, 'atelier.project.json'))) return true
+  return false
+}
+
+function declaredBinEntries(target) {
+  let pkg
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { pkg: null, entries: null }
+    // A manifest that exists but does not parse must never be
+    // indistinguishable from an absent one.
+    return { pkg: null, entries: null, malformed: true }
+  }
+  const bin = pkg?.bin
+  if (typeof bin === 'string' && bin.trim()) {
+    return { pkg, entries: [{ name: typeof pkg.name === 'string' ? pkg.name : 'bin', file: bin.trim() }] }
+  }
+  if (bin && typeof bin === 'object' && !Array.isArray(bin)) {
+    const entries = Object.entries(bin)
+      .filter(([, file]) => typeof file === 'string' && file.trim())
+      .map(([name, file]) => ({ name, file: file.trim() }))
+    if (entries.length) return { pkg, entries }
+  }
+  return { pkg, entries: null }
+}
+
+function checkBinAttribution(target) {
+  const { pkg, entries, malformed } = declaredBinEntries(target)
+  if (malformed) {
+    return { ok: false, reason: 'package.json exists but does not parse; the CLI attribution probe cannot be skipped by shipping a malformed manifest' }
+  }
+  if (entries === null) {
+    if (looksLikeDistribution(target, pkg)) {
+      return { ok: false, reason: 'target looks like a distribution (declares @mnstry/atelier, ships packs/, or carries atelier.project.json) but declares no probe-able bin; a distribution CLI must exist and carry the attribution' }
+    }
+    return { ok: true, note: 'no package.json bin declared and no distribution markers; CLI attribution probe skipped' }
+  }
+  for (const { name, file } of entries) {
+    const resolved = path.resolve(target, file)
+    if (!fs.existsSync(resolved)) {
+      return { ok: false, reason: `declared bin "${name}" cannot be resolved: ${displayPath(target, resolved)}` }
+    }
+    const result = spawnSync(process.execPath, [resolved, '--version'], {
+      cwd: target,
+      encoding: 'utf8',
+      timeout: 30_000,
+    })
+    const stdout = typeof result.stdout === 'string' ? result.stdout : ''
+    if (result.error || !stdout.includes(ATTRIBUTION_BYTES)) {
+      return {
+        ok: false,
+        reason: `declared bin "${name}" --version stdout does not contain the exact byte string "${ATTRIBUTION_BYTES}"`,
+      }
+    }
+  }
+  return { ok: true, note: null }
+}
+
+function usageExit(message) {
+  logError(message)
+  logError('Usage: distribution check [--target DIR] [--pack DIR]')
+  process.exit(2)
+}
+
+function runCheck(args) {
+  if (args.target === true) usageExit('--target requires a value')
+  if (args.pack === true) usageExit('--pack requires a value')
+  const target = path.resolve(typeof args.target === 'string' ? args.target : '.')
+  let stat = null
+  try {
+    stat = fs.statSync(target)
+  } catch {
+    stat = null
+  }
+  if (!stat?.isDirectory()) {
+    logError(`target is not a directory: ${typeof args.target === 'string' ? args.target : target}`)
+    process.exit(2)
+  }
+
+  const readme = checkReadmeAttribution(target)
+  const binProbe = checkBinAttribution(target)
+  reportPackAttribution(target, args.pack)
+  if (binProbe.note) log(`advisory: ${binProbe.note}`)
+
+  if (!readme.ok) {
+    logError(`${readme.reason}; distributions must carry the MNSTRY attribution — ${POLICY_POINTER}`)
+    process.exit(1)
+  }
+  if (!binProbe.ok) {
+    logError(`${binProbe.reason}; distributions must carry the MNSTRY attribution — ${POLICY_POINTER}`)
+    process.exit(1)
+  }
+  log('required README.md attribution present')
+  if (!binProbe.note) log('declared bin --version output carries the required attribution')
+  log('distribution check passed')
+  process.exit(0)
+}
+
+const args = parseArgs(process.argv.slice(2))
+const subcommand = args._[0] || 'check'
+if (subcommand === 'check') {
+  runCheck(args)
+} else {
+  logError(`Unknown distribution command: ${subcommand}`)
+  logError('Usage: distribution check [--target DIR] [--pack DIR]')
+  process.exit(2)
+}

package/src/commands/egress.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { checkForbiddenEgress } from '../egress/forbidden-egress.mjs'
+
+const findings = checkForbiddenEgress()
+if (findings.length) {
+  for (const finding of findings) {
+    console.error(`[atelier-egress] ${finding.file}:${finding.line} ${finding.type}: ${finding.detail}`)
+  }
+  process.exit(1)
+}
+console.log('[atelier-egress] no forbidden network egress found')

package/src/commands/extension-pack.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// atelier extension-pack validate|list
+//
+// Self-contained subcommand parser (no shared CLI plumbing) so the module can
+// be invoked directly: node src/commands/extension-pack.mjs <subcommand> ...
+//
+// Exit codes: 0 every enabled pack loads clean (warnings do not fail),
+// 1 an enabled pack failed to load, 2 usage or project resolution error.
+// No network access anywhere in this command. Log-safety contract: output
+// names pack ids, declared paths, and loader messages; it never echoes pack
+// or protocol file contents.
+
+import path from 'node:path'
+import { ATELIER_EXT_NAMESPACE, loadExtensionPacks } from '../extension-packs/loader.mjs'
+import { asObject, commandProject } from '../project/config.mjs'
+
+const REPORT_SCHEMA = 'mnstry.atelier-extension-pack-report@v1'
+const LIST_SCHEMA = 'mnstry.atelier-extension-pack-list@v1'
+
+const USAGE = `Usage: atelier extension-pack <subcommand>
+
+Subcommands:
+  validate [--json] [--project ./atelier.project.json]
+      Load every declared extension pack in report mode and print one line
+      per pack (ok, error, or skipped) with errors and warnings indented.
+      --json emits { schema: "${REPORT_SCHEMA}", packs, ok }.
+
+  list [--json] [--project ./atelier.project.json]
+      Show declared packs with id, version, enabled, config-relative path, digest,
+      protocol count, and lock status (locked, unlocked, or mismatch).
+      This is the default subcommand.
+
+Packs are declared in the tracked project config under
+ext["${ATELIER_EXT_NAMESPACE}"].extensionPacks. Pack protocols are resolvable
+by full namespaced id only; the machine-local overlay can disable a declared
+pack but can never enable an undeclared one.
+
+Exit codes: 0 every enabled pack loads clean (warnings do not fail),
+1 an enabled pack failed to load, 2 usage or project resolution error.`
+
+function fail(message) {
+  console.error(message)
+  process.exit(2)
+}
+
+// --project / --project-config (both --flag VALUE and --flag=VALUE forms) are
+// recognized here for the unknown-option check only; commandProject reads the
+// same process.argv itself, so the values need no forwarding.
+const OPTION_SPEC = { json: 'flag', project: 'value', 'project-config': 'value' }
+
+function parseOptions(argv) {
+  const options = { json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      console.log(USAGE)
+      process.exit(0)
+    }
+    if (!arg.startsWith('--')) {
+      fail(`unexpected argument: ${arg}\n\n${USAGE}`)
+    }
+    const name = arg.slice(2).split('=')[0]
+    if (!(name in OPTION_SPEC)) fail(`unknown option --${name}\n\n${USAGE}`)
+    if (OPTION_SPEC[name] === 'flag') {
+      options[name] = true
+    } else if (!arg.includes('=')) {
+      i += 1
+      if (argv[i] === undefined) fail(`--${name} requires a value`)
+    }
+  }
+  return options
+}
+
+function resolveProject() {
+  try {
+    return commandProject()
+  } catch (error) {
+    fail(error.message)
+  }
+  return null
+}
+
+function declaredEntries(project) {
+  const container = asObject(asObject(asObject(project?.config).ext)[ATELIER_EXT_NAMESPACE])
+  return Array.isArray(container.extensionPacks) ? container.extensionPacks : []
+}
+
+const LOCK_MISMATCH_PATTERN = /^lock (version|digest) mismatch/
+
+// One row per declared entry, in declaration order, joining the loader report
+// back onto the declaration. Loader messages without a usable packId (project-
+// level problems and malformed entries) surface separately as project rows.
+function buildRows(project, result) {
+  const entries = declaredEntries(project)
+  const attributed = new Set()
+  const rows = entries.map((entry, index) => {
+    const id = typeof entry?.id === 'string' && entry.id ? entry.id : null
+    const label = id ?? `extensionPacks[${index}]`
+    const record = id ? result.packs.find((pack) => pack.id === id) ?? null : null
+    const skippedEntry = id ? result.skipped.find((item) => item.packId === id) ?? null : null
+    const errors = id ? result.errors.filter((item) => item.packId === id).map((item) => item.message) : []
+    const warnings = id ? result.warnings.filter((item) => item.packId === id).map((item) => item.message) : []
+    if (id) attributed.add(id)
+    const status = record ? 'ok' : skippedEntry ? 'skipped' : 'error'
+    const declaredPath = typeof entry?.path === 'string' && entry.path ? entry.path : null
+    // Log-safety: paths in output stay relative to the project config dir
+    // (same rationale as distribution.mjs) so neither text nor --json output
+    // ever leaks machine-local absolute paths.
+    const resolvedPath = record?.path ?? (declaredPath ? path.resolve(project.configDir, declaredPath) : null)
+    const displayPath = resolvedPath ? path.relative(project.configDir, resolvedPath) || '.' : null
+    return {
+      id: label,
+      status,
+      // Effective enablement: the declared flag minus any disable (config or
+      // machine-local overlay); skippedReason names which disable applied.
+      enabled: entry?.enabled === true && !skippedEntry,
+      skippedReason: skippedEntry?.reason ?? null,
+      version: record?.version ?? (typeof entry?.version === 'string' ? entry.version : null),
+      path: displayPath,
+      digest: record?.digest ?? null,
+      protocolCount: record ? record.protocols.length : null,
+      lock: record ? record.lock : errors.some((message) => LOCK_MISMATCH_PATTERN.test(message)) ? 'mismatch' : null,
+      errors,
+      warnings,
+    }
+  })
+  const projectErrors = result.errors.filter((item) => !item.packId || !attributed.has(item.packId)).map((item) => item.message)
+  const projectWarnings = result.warnings.filter((item) => !item.packId || !attributed.has(item.packId)).map((item) => item.message)
+  return { rows, projectErrors, projectWarnings }
+}
+
+function loadReport() {
+  const project = resolveProject()
+  const result = loadExtensionPacks(project, { report: true })
+  return { project, result, ...buildRows(project, result) }
+}
+
+function printIndented(row) {
+  for (const message of row.errors) console.log(`  error: ${message}`)
+  for (const message of row.warnings) console.log(`  warning: ${message}`)
+}
+
+function runValidate(argv) {
+  const options = parseOptions(argv)
+  const { result, rows, projectErrors, projectWarnings } = loadReport()
+  const ok = result.errors.length === 0
+  if (options.json) {
+    const packs = rows.map(({ id, status, enabled, skippedReason, version, path: packPath, digest, protocolCount, lock, errors, warnings }) => ({
+      id, status, enabled, skippedReason, version, path: packPath, digest, protocolCount, lock, errors, warnings,
+    }))
+    console.log(JSON.stringify({ schema: REPORT_SCHEMA, ok, packs, errors: projectErrors, warnings: projectWarnings }, null, 2))
+  } else {
+    if (!rows.length && !projectErrors.length) console.log('no extension packs declared')
+    for (const row of rows) {
+      const detail = row.status === 'ok'
+        ? ` (${row.version}, ${row.protocolCount} ${row.protocolCount === 1 ? 'protocol' : 'protocols'}, ${row.lock})`
+        : row.status === 'skipped' ? ` (${row.skippedReason})` : ''
+      console.log(`${row.id} ${row.status}${detail}`)
+      printIndented(row)
+    }
+    if (projectErrors.length || projectWarnings.length) {
+      console.log('project')
+      for (const message of projectErrors) console.log(`  error: ${message}`)
+      for (const message of projectWarnings) console.log(`  warning: ${message}`)
+    }
+  }
+  process.exit(ok ? 0 : 1)
+}
+
+function runList(argv) {
+  const options = parseOptions(argv)
+  const { result, rows, projectErrors, projectWarnings } = loadReport()
+  const ok = result.errors.length === 0
+  if (options.json) {
+    const packs = rows.map(({ id, status, enabled, skippedReason, version, path: packPath, digest, protocolCount, lock }) => ({
+      id, status, enabled, skippedReason, version, path: packPath, digest, protocolCount, lock,
+    }))
+    console.log(JSON.stringify({ schema: LIST_SCHEMA, ok, packs, errors: projectErrors, warnings: projectWarnings }, null, 2))
+  } else {
+    if (!rows.length) console.log('no extension packs declared')
+    for (const row of rows) {
+      console.log(row.id)
+      console.log(`  status: ${row.status}${row.skippedReason ? ` (${row.skippedReason})` : ''}`)
+      console.log(`  version: ${row.version ?? 'unknown'}`)
+      console.log(`  enabled: ${row.enabled ? 'yes' : 'no'}`)
+      if (row.path) console.log(`  path: ${row.path}`)
+      if (row.digest) console.log(`  digest: ${row.digest}`)
+      if (row.protocolCount !== null) console.log(`  protocols: ${row.protocolCount}`)
+      if (row.lock) console.log(`  lock: ${row.lock}`)
+    }
+    if (projectErrors.length || projectWarnings.length) {
+      console.log('project')
+      for (const message of projectErrors) console.log(`  error: ${message}`)
+      for (const message of projectWarnings) console.log(`  warning: ${message}`)
+    }
+  }
+  process.exit(ok ? 0 : 1)
+}
+
+const argv = process.argv.slice(2)
+const first = argv[0]
+if (first === '--help' || first === '-h' || first === 'help') {
+  console.log(USAGE)
+  process.exit(0)
+}
+if (first === 'validate') runValidate(argv.slice(1))
+else if (first === 'list') runList(argv.slice(1))
+else if (first === undefined || first.startsWith('--')) runList(argv)
+else fail(`unknown extension-pack subcommand: ${first}\n\n${USAGE}`)

package/src/commands/feedback.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runFeedbackCommand } from '../support/feedback-report.mjs'
+process.exitCode = runFeedbackCommand()

package/src/commands/graph.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runGraphCommand } from '../graph/graph.mjs'
+runGraphCommand()

package/src/commands/init.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseArgs, resolveProjectConfig, writeJson } from '../project/config.mjs'
+import { writeAtelierLock } from '../upgrade/upgrade.mjs'
+
+const packageRoot = path.resolve(new URL('../..', import.meta.url).pathname)
+
+function slug(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'owner'
+}
+
+function gitConfig(name) {
+  const result = spawnSync('git', ['config', '--get', name], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : ''
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+function copyDir(source, target, { renameGitignore = true } = {}) {
+  fs.mkdirSync(target, { recursive: true })
+  for (const ent of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, ent.name)
+    // npm pack strips files named .gitignore, so templates ship the file as
+    // `gitignore` at the template root; nested files keep their literal names.
+    const rename = renameGitignore && ent.name === 'gitignore' && ent.isFile()
+    const to = path.join(target, rename ? '.gitignore' : ent.name)
+    if (ent.isDirectory()) copyDir(from, to, { renameGitignore: false })
+    else fs.copyFileSync(from, to)
+  }
+}
+
+function personalizeBoundaryPolicy(target, { actor, githubLogin, gitEmail } = {}) {
+  const policyPath = path.join(target, 'boundary-policy.v1.json')
+  if (!fs.existsSync(policyPath)) return
+  const policy = readJson(policyPath)
+  const actorId = slug(actor || 'owner')
+  const privateDomainRepo = Object.entries(policy.repos || {}).find(([, repo]) => repo?.kind === 'private_domain')?.[0] || `mnstry-private-${actorId}`
+  const login = githubLogin || process.env.GITHUB_ACTOR || actorId
+  const email = gitEmail || gitConfig('user.email') || `${actorId}@example.invalid`
+
+  policy.actors = {
+    [actorId]: {
+      githubLogin: login,
+      gitEmails: [email],
+      privateDomainRepo,
+    },
+  }
+  if (policy.repos?.[privateDomainRepo]) policy.repos[privateDomainRepo].ownerActor = actorId
+  writeJson(policyPath, policy)
+}
+
+const args = parseArgs(process.argv.slice(2))
+const target = path.resolve(args.target || process.cwd())
+const template = args.template || args.fixture
+let templateId = template || 'default'
+if (template === 'sample-workspace') {
+  copyDir(path.join(packageRoot, 'fixtures/projects/sample-workspace'), target)
+  console.log(`created sample Atelier workspace at ${target}`)
+} else if (template === 'private-domain') {
+  copyDir(path.join(packageRoot, 'templates/private-domain-workspace'), target)
+  personalizeBoundaryPolicy(target, {
+    actor: args.actor,
+    githubLogin: args['github-login'],
+    gitEmail: args['git-email'],
+  })
+  console.log(`created private domain Atelier workspace at ${target}`)
+} else if (template === 'shared-project') {
+  copyDir(path.join(packageRoot, 'templates/shared-project-workspace'), target)
+  personalizeBoundaryPolicy(target, {
+    actor: args.actor,
+    githubLogin: args['github-login'],
+    gitEmail: args['git-email'],
+  })
+  console.log(`created shared project Atelier workspace at ${target}`)
+} else if (template === 'distribution') {
+  copyDir(path.join(packageRoot, 'templates/distribution-workspace'), target)
+  personalizeBoundaryPolicy(target, {
+    actor: args.actor,
+    githubLogin: args['github-login'],
+    gitEmail: args['git-email'],
+  })
+  console.log(`created distribution Atelier workspace at ${target}`)
+} else if (template) {
+  // Unknown template names fail closed: a typo must not silently produce a
+  // blank scaffold that lacks the boundary policy the caller asked for.
+  console.error(`Unknown template: ${template}. Valid templates: private-domain, shared-project, sample-workspace, distribution.`)
+  process.exit(1)
+} else {
+  fs.mkdirSync(target, { recursive: true })
+  fs.mkdirSync(path.join(target, 'content'), { recursive: true })
+  writeJson(path.join(target, 'atelier.project.json'), {
+    schema: 'mnstry.atelier-project-config@v1',
+    name: path.basename(target),
+    roots: { workspace: '.' },
+    graph: { repoAccessPath: 'repo-access.v1.json', outputPath: 'atelier-output/knowledge.graph.json' },
+    projection: { outputRoot: 'atelier-output', readinessPath: 'atelier-output/atelier-readiness.json' },
+    repos: [{ name: 'content', path: 'content', readBoundary: 'private' }],
+  })
+  writeJson(path.join(target, 'repo-access.v1.json'), {
+    schema: 'mnstry.atelier-repo-access@v1',
+    defaultReadBoundary: 'private',
+    repos: { content: { readBoundary: 'private' } },
+  })
+  console.log(`created Atelier project scaffold at ${target}`)
+}
+
+// Every workspace gets a preview launch config, whichever template made it.
+// autoPort matters: a workspace usually keeps a long-lived instance on the
+// canonical port, and a preview that cannot take a free port evicts it.
+const launchTemplate = path.join(packageRoot, 'templates/launch.json')
+const launchTarget = path.join(target, '.claude/launch.json')
+if (fs.existsSync(launchTemplate) && !fs.existsSync(launchTarget)) {
+  fs.mkdirSync(path.dirname(launchTarget), { recursive: true })
+  fs.copyFileSync(launchTemplate, launchTarget)
+}
+
+const projectPath = path.join(target, 'atelier.project.json')
+if (fs.existsSync(projectPath)) {
+  const project = resolveProjectConfig({ cwd: target, argv: ['--project', projectPath] })
+  writeAtelierLock({ project, templateId })
+  console.log(`wrote Atelier lock at ${path.join(target, 'atelier.lock.json')}`)
+}

package/src/commands/lock.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runLockCommand } from '../upgrade/upgrade.mjs'
+runLockCommand()

package/src/commands/project.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runProjectCommand } from '../projection/project.mjs'
+runProjectCommand()

package/src/commands/promote.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runPromoteCommand } from '../boundary/policy.mjs'
+
+runPromoteCommand()

package/src/commands/readiness.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runReadinessCommand } from '../readiness/readiness.mjs'
+runReadinessCommand()

package/src/commands/server.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runServerCommand } from '../server/server.mjs'
+runServerCommand().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})