@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/lib/npm.js

@@ -0,0 +1,113 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isFileLinkedFromProject, isWorkspaceMember } from './project.js';
+/** The npm executable name for the current platform. */
+export function npmBin() {
+    return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+/**
+ * Whether npm must be spawned through a shell. Node refuses to spawn a `.cmd`
+ * file without one on Windows (EINVAL since the CVE-2024-27980 fix), so win32
+ * needs `shell: true`. A shell joins argv unescaped, which is why every caller
+ * passes fixed arguments or specs checked against `INSTALL_SPEC_RE` only.
+ */
+export function npmNeedsShell() {
+    return process.platform === 'win32';
+}
+/** A bare or scoped npm package name — nothing a shell would interpret. */
+export const NPM_PACKAGE_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/**
+ * What `installPackages` hands to `npm install`: a package name with an optional
+ * `@version` / `@range`, or `github:owner/repo[#ref]`. No quote, `%`, `&`, `;`,
+ * `$`, space or newline can appear, so a spec is safe to pass through a shell
+ * once double-quoted (see `shellArg`); quoting keeps a range's `^ < > |` literal.
+ */
+export const INSTALL_SPEC_RE = /^(?:(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[0-9A-Za-z.~^*<>=|+-]+)?|github:[A-Za-z0-9][\w.-]*\/[\w.-]+(?:#[\w./-]+)?)$/;
+/** A checked spec as one argument: quoted when npm runs through a shell. */
+function shellArg(spec) {
+    return npmNeedsShell() ? `"${spec}"` : spec;
+}
+/**
+ * Runs `npm install` in `dir` (best-effort). Streams npm's output so progress is
+ * visible. Never throws: a missing `package.json`, a missing `npm`, or a
+ * non-zero exit is reported via the result so the scaffold still succeeds and
+ * the user can install manually.
+ */
+export function installDeps(dir, run = true, extraArgs = []) {
+    if (!run)
+        return { ok: true, skipped: true, message: 'install skipped (--no-install)' };
+    if (!existsSync(join(dir, 'package.json'))) {
+        return { ok: true, skipped: true, message: 'no package.json — nothing to install' };
+    }
+    const res = spawnSync(npmBin(), ['install', ...extraArgs], {
+        cwd: dir,
+        stdio: 'inherit',
+        env: process.env,
+        shell: npmNeedsShell(),
+    });
+    if (res.error) {
+        const missing = res.error.code === 'ENOENT';
+        return {
+            ok: false,
+            message: missing
+                ? 'npm was not found on PATH — install dependencies manually.'
+                : `npm install failed to start: ${res.error.message}`,
+        };
+    }
+    if (typeof res.status === 'number' && res.status !== 0) {
+        return { ok: false, message: `npm install exited with code ${res.status}.` };
+    }
+    return { ok: true };
+}
+/**
+ * Adds one or more packages to `dir`'s `dependencies` and installs them
+ * (`npm install <pkg>...`), so the runtime can later resolve them from the
+ * project's `node_modules`. Same best-effort, never-throw contract as
+ * `installDeps`: a missing `npm`, a missing manifest, or a non-zero exit is
+ * reported via the result rather than thrown. No-ops when `packages` is empty.
+ */
+export function installPackages(dir, packages, run = true, extraArgs = []) {
+    if (!run)
+        return { ok: true, skipped: true, message: 'install skipped (--no-install)' };
+    if (packages.length === 0) {
+        return { ok: true, skipped: true, message: 'no packages to install' };
+    }
+    if (!existsSync(join(dir, 'package.json'))) {
+        return { ok: false, message: 'no package.json — run `mdk onboard` first' };
+    }
+    const invalid = packages.find((spec) => !INSTALL_SPEC_RE.test(spec));
+    if (invalid)
+        return { ok: false, message: `refusing to install "${invalid}": not a valid npm package or GitHub spec` };
+    const res = spawnSync(npmBin(), ['install', ...extraArgs, ...packages.map(shellArg)], {
+        cwd: dir,
+        stdio: 'inherit',
+        env: process.env,
+        shell: npmNeedsShell(),
+    });
+    if (res.error) {
+        const missing = res.error.code === 'ENOENT';
+        return {
+            ok: false,
+            message: missing
+                ? 'npm was not found on PATH — install the plugins manually.'
+                : `npm install failed to start: ${res.error.message}`,
+        };
+    }
+    if (typeof res.status === 'number' && res.status !== 0) {
+        return { ok: false, message: `npm install exited with code ${res.status}.` };
+    }
+    return { ok: true };
+}
+/**
+ * Installs dependencies for a freshly scaffolded component. When the package is
+ * a workspace member or already declared as a `file:` dep of the project root,
+ * npm must run at the project root so the symlink lands in the project's
+ * `node_modules`. Everything else installs in its own directory.
+ */
+export function installScaffold(projectDir, packageDir, run = true) {
+    const atRoot = isWorkspaceMember(projectDir, packageDir) || isFileLinkedFromProject(projectDir, packageDir);
+    const dir = atRoot ? projectDir : packageDir;
+    return { ...installDeps(dir, run), dir };
+}
+//# sourceMappingURL=npm.js.map

package/dist/lib/npm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm.js","sourceRoot":"","sources":["../../src/lib/npm.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'node:child_process';\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { isFileLinkedFromProject, isWorkspaceMember } from './project.js';\n\nexport interface InstallResult {\n  ok: boolean;\n  /** Skipped when there is nothing to install (no package.json) or `run: false`. */\n  skipped?: boolean;\n  message?: string;\n}\n\nexport interface ScaffoldInstall extends InstallResult {\n  /** The directory npm actually ran in — the workspace root, or the package. */\n  dir: string;\n}\n\n/** The npm executable name for the current platform. */\nexport function npmBin(): string {\n  return process.platform === 'win32' ? 'npm.cmd' : 'npm';\n}\n\n/**\n * Whether npm must be spawned through a shell. Node refuses to spawn a `.cmd`\n * file without one on Windows (EINVAL since the CVE-2024-27980 fix), so win32\n * needs `shell: true`. A shell joins argv unescaped, which is why every caller\n * passes fixed arguments or specs checked against `INSTALL_SPEC_RE` only.\n */\nexport function npmNeedsShell(): boolean {\n  return process.platform === 'win32';\n}\n\n/** A bare or scoped npm package name — nothing a shell would interpret. */\nexport const NPM_PACKAGE_RE = /^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$/;\n\n/**\n * What `installPackages` hands to `npm install`: a package name with an optional\n * `@version` / `@range`, or `github:owner/repo[#ref]`. No quote, `%`, `&`, `;`,\n * `$`, space or newline can appear, so a spec is safe to pass through a shell\n * once double-quoted (see `shellArg`); quoting keeps a range's `^ < > |` literal.\n */\nexport const INSTALL_SPEC_RE =\n  /^(?:(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*(?:@[0-9A-Za-z.~^*<>=|+-]+)?|github:[A-Za-z0-9][\\w.-]*\\/[\\w.-]+(?:#[\\w./-]+)?)$/;\n\n/** A checked spec as one argument: quoted when npm runs through a shell. */\nfunction shellArg(spec: string): string {\n  return npmNeedsShell() ? `\"${spec}\"` : spec;\n}\n\n/**\n * Runs `npm install` in `dir` (best-effort). Streams npm's output so progress is\n * visible. Never throws: a missing `package.json`, a missing `npm`, or a\n * non-zero exit is reported via the result so the scaffold still succeeds and\n * the user can install manually.\n */\nexport function installDeps(dir: string, run = true, extraArgs: string[] = []): InstallResult {\n  if (!run) return { ok: true, skipped: true, message: 'install skipped (--no-install)' };\n  if (!existsSync(join(dir, 'package.json'))) {\n    return { ok: true, skipped: true, message: 'no package.json — nothing to install' };\n  }\n\n  const res = spawnSync(npmBin(), ['install', ...extraArgs], {\n    cwd: dir,\n    stdio: 'inherit',\n    env: process.env,\n    shell: npmNeedsShell(),\n  });\n\n  if (res.error) {\n    const missing = (res.error as NodeJS.ErrnoException).code === 'ENOENT';\n    return {\n      ok: false,\n      message: missing\n        ? 'npm was not found on PATH — install dependencies manually.'\n        : `npm install failed to start: ${res.error.message}`,\n    };\n  }\n  if (typeof res.status === 'number' && res.status !== 0) {\n    return { ok: false, message: `npm install exited with code ${res.status}.` };\n  }\n  return { ok: true };\n}\n\n/**\n * Adds one or more packages to `dir`'s `dependencies` and installs them\n * (`npm install <pkg>...`), so the runtime can later resolve them from the\n * project's `node_modules`. Same best-effort, never-throw contract as\n * `installDeps`: a missing `npm`, a missing manifest, or a non-zero exit is\n * reported via the result rather than thrown. No-ops when `packages` is empty.\n */\nexport function installPackages(dir: string, packages: string[], run = true, extraArgs: string[] = []): InstallResult {\n  if (!run) return { ok: true, skipped: true, message: 'install skipped (--no-install)' };\n  if (packages.length === 0) {\n    return { ok: true, skipped: true, message: 'no packages to install' };\n  }\n  if (!existsSync(join(dir, 'package.json'))) {\n    return { ok: false, message: 'no package.json — run `mdk onboard` first' };\n  }\n\n  const invalid = packages.find((spec) => !INSTALL_SPEC_RE.test(spec));\n  if (invalid) return { ok: false, message: `refusing to install \"${invalid}\": not a valid npm package or GitHub spec` };\n\n  const res = spawnSync(npmBin(), ['install', ...extraArgs, ...packages.map(shellArg)], {\n    cwd: dir,\n    stdio: 'inherit',\n    env: process.env,\n    shell: npmNeedsShell(),\n  });\n\n  if (res.error) {\n    const missing = (res.error as NodeJS.ErrnoException).code === 'ENOENT';\n    return {\n      ok: false,\n      message: missing\n        ? 'npm was not found on PATH — install the plugins manually.'\n        : `npm install failed to start: ${res.error.message}`,\n    };\n  }\n  if (typeof res.status === 'number' && res.status !== 0) {\n    return { ok: false, message: `npm install exited with code ${res.status}.` };\n  }\n  return { ok: true };\n}\n\n/**\n * Installs dependencies for a freshly scaffolded component. When the package is\n * a workspace member or already declared as a `file:` dep of the project root,\n * npm must run at the project root so the symlink lands in the project's\n * `node_modules`. Everything else installs in its own directory.\n */\nexport function installScaffold(\n  projectDir: string,\n  packageDir: string,\n  run = true,\n): ScaffoldInstall {\n  const atRoot =\n    isWorkspaceMember(projectDir, packageDir) || isFileLinkedFromProject(projectDir, packageDir);\n  const dir = atRoot ? projectDir : packageDir;\n  return { ...installDeps(dir, run), dir };\n}\n"]}

package/dist/lib/package-source.js

@@ -0,0 +1,76 @@
+import { INSTALL_SPEC_RE } from './npm.js';
+import { isLocalPackagePath } from './spec.js';
+// The owner starts with a letter or digit, so `../x` is never read as a repo;
+// a ref is a branch, tag or SHA (`/` allowed for `release/1.x`).
+const GITHUB_URL = /^(?:git\+)?https:\/\/github\.com\/([A-Za-z0-9][\w.-]*)\/([\w.-]+?)(?:\.git)?(?:#([\w./-]+))?$/;
+const GITHUB_SHORTHAND = /^(?:github:)?([A-Za-z0-9][\w.-]*)\/([\w.-]+?)(?:\.git)?(?:#([\w./-]+))?$/;
+const NPM_NAME = /^[a-z0-9][a-z0-9._~-]*$/;
+function github(owner, repo, ref) {
+    return { kind: 'github', installSpec: `github:${owner}/${repo}${ref ? `#${ref}` : ''}` };
+}
+/**
+ * Classifies an `mdk add` source:
+ *
+ * - `github:owner/repo[#ref]`, `owner/repo[#ref]` or `https://github.com/owner/repo[.git][#ref]`
+ * - an npm spec: `pkg`, `pkg@1.2.3`, `@scope/pkg[@range]`, with an optional trailing subpath
+ *   (`@scope/pkg/apps/ops`) naming a directory inside the package.
+ *
+ * `owner/repo` is read as GitHub, as npm itself does; an unscoped npm package with a
+ * subpath is therefore ambiguous and has to be written `pkg@latest/sub`.
+ */
+export function parseSource(raw) {
+    const source = raw.trim();
+    if (!source)
+        throw new Error('Give a package source: an npm package or a GitHub repo (owner/repo).');
+    if (isLocalPackagePath(source) || source.startsWith('file:') || source.startsWith('~')) {
+        throw new Error(`"${raw}" is a path. \`mdk add\` installs from npm or GitHub; for a package on disk, ` +
+            'reference it by path in mdk.yaml (`package: ./apps/<name>`), or scaffold one with `mdk create`.');
+    }
+    const url = GITHUB_URL.exec(source);
+    if (url)
+        return github(url[1], url[2], url[3]);
+    if (source.startsWith('github:')) {
+        const short = GITHUB_SHORTHAND.exec(source);
+        if (!short)
+            throw new Error(`"${raw}" is not a valid GitHub source (expected github:owner/repo[#ref]).`);
+        return github(short[1], short[2], short[3]);
+    }
+    if (!source.startsWith('@')) {
+        const short = GITHUB_SHORTHAND.exec(source);
+        if (short && !source.includes('@'))
+            return github(short[1], short[2], short[3]);
+    }
+    const segments = source.split('/');
+    const nameSegments = source.startsWith('@') ? 2 : 1;
+    const head = segments.slice(0, nameSegments);
+    const subpath = segments.slice(nameSegments).join('/');
+    if (head.length < nameSegments || (source.startsWith('@') && head[0].length < 2)) {
+        throw new Error(`"${raw}" is not a valid npm package (expected @scope/name).`);
+    }
+    // `name@range` carries the version on the last name segment.
+    const last = head[head.length - 1];
+    const at = last.indexOf('@');
+    const bareLast = at === -1 ? last : last.slice(0, at);
+    const range = at === -1 ? '' : last.slice(at);
+    const bareHead = [...head.slice(0, -1), bareLast];
+    const packageName = bareHead.join('/');
+    const nameOnly = bareHead[bareHead.length - 1];
+    if (!NPM_NAME.test(nameOnly) || (nameSegments === 2 && !/^@[a-z0-9][a-z0-9._~-]*$/.test(bareHead[0]))) {
+        throw new Error(`"${raw}" is not a valid npm package name.`);
+    }
+    if (at !== -1 && range.length < 2)
+        throw new Error(`"${raw}" has an empty version after "@".`);
+    if (subpath && !subpath.split('/').every((s) => /^[A-Za-z0-9_][\w.-]*$/.test(s))) {
+        throw new Error(`"${raw}" is not a valid package subpath (directory names only, no "..").`);
+    }
+    if (range && !INSTALL_SPEC_RE.test(`${packageName}${range}`)) {
+        throw new Error(`"${raw}" has a version npm install cannot take as one argument (no spaces; use e.g. ^1.2.0).`);
+    }
+    return {
+        kind: 'npm',
+        installSpec: `${packageName}${range}`,
+        packageName,
+        ...(subpath ? { subpath } : {}),
+    };
+}
+//# sourceMappingURL=package-source.js.map

package/dist/lib/package-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-source.js","sourceRoot":"","sources":["../../src/lib/package-source.ts"],"names":[],"mappings":"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","sourcesContent":["import { INSTALL_SPEC_RE } from './npm.js';\nimport { isLocalPackagePath } from './spec.js';\n\n/**\n * Where `mdk add` installs a package from: the npm registry or a GitHub repo.\n */\nexport interface PackageSource {\n  kind: 'npm' | 'github';\n  /** The argument handed to `npm install`. */\n  installSpec: string;\n  /** Known up front for npm (the package part of the spec); learnt from the install for GitHub. */\n  packageName?: string;\n  /** A directory inside the installed package (npm packages that ship several apps). */\n  subpath?: string;\n}\n\n// The owner starts with a letter or digit, so `../x` is never read as a repo;\n// a ref is a branch, tag or SHA (`/` allowed for `release/1.x`).\nconst GITHUB_URL = /^(?:git\\+)?https:\\/\\/github\\.com\\/([A-Za-z0-9][\\w.-]*)\\/([\\w.-]+?)(?:\\.git)?(?:#([\\w./-]+))?$/;\nconst GITHUB_SHORTHAND = /^(?:github:)?([A-Za-z0-9][\\w.-]*)\\/([\\w.-]+?)(?:\\.git)?(?:#([\\w./-]+))?$/;\nconst NPM_NAME = /^[a-z0-9][a-z0-9._~-]*$/;\n\nfunction github(owner: string, repo: string, ref?: string): PackageSource {\n  return { kind: 'github', installSpec: `github:${owner}/${repo}${ref ? `#${ref}` : ''}` };\n}\n\n/**\n * Classifies an `mdk add` source:\n *\n * - `github:owner/repo[#ref]`, `owner/repo[#ref]` or `https://github.com/owner/repo[.git][#ref]`\n * - an npm spec: `pkg`, `pkg@1.2.3`, `@scope/pkg[@range]`, with an optional trailing subpath\n *   (`@scope/pkg/apps/ops`) naming a directory inside the package.\n *\n * `owner/repo` is read as GitHub, as npm itself does; an unscoped npm package with a\n * subpath is therefore ambiguous and has to be written `pkg@latest/sub`.\n */\nexport function parseSource(raw: string): PackageSource {\n  const source = raw.trim();\n  if (!source) throw new Error('Give a package source: an npm package or a GitHub repo (owner/repo).');\n  if (isLocalPackagePath(source) || source.startsWith('file:') || source.startsWith('~')) {\n    throw new Error(\n      `\"${raw}\" is a path. \\`mdk add\\` installs from npm or GitHub; for a package on disk, ` +\n        'reference it by path in mdk.yaml (`package: ./apps/<name>`), or scaffold one with `mdk create`.',\n    );\n  }\n\n  const url = GITHUB_URL.exec(source);\n  if (url) return github(url[1]!, url[2]!, url[3]);\n\n  if (source.startsWith('github:')) {\n    const short = GITHUB_SHORTHAND.exec(source);\n    if (!short) throw new Error(`\"${raw}\" is not a valid GitHub source (expected github:owner/repo[#ref]).`);\n    return github(short[1]!, short[2]!, short[3]);\n  }\n\n  if (!source.startsWith('@')) {\n    const short = GITHUB_SHORTHAND.exec(source);\n    if (short && !source.includes('@')) return github(short[1]!, short[2]!, short[3]);\n  }\n\n  const segments = source.split('/');\n  const nameSegments = source.startsWith('@') ? 2 : 1;\n  const head = segments.slice(0, nameSegments);\n  const subpath = segments.slice(nameSegments).join('/');\n  if (head.length < nameSegments || (source.startsWith('@') && head[0]!.length < 2)) {\n    throw new Error(`\"${raw}\" is not a valid npm package (expected @scope/name).`);\n  }\n\n  // `name@range` carries the version on the last name segment.\n  const last = head[head.length - 1]!;\n  const at = last.indexOf('@');\n  const bareLast = at === -1 ? last : last.slice(0, at);\n  const range = at === -1 ? '' : last.slice(at);\n  const bareHead = [...head.slice(0, -1), bareLast];\n  const packageName = bareHead.join('/');\n  const nameOnly = bareHead[bareHead.length - 1]!;\n  if (!NPM_NAME.test(nameOnly) || (nameSegments === 2 && !/^@[a-z0-9][a-z0-9._~-]*$/.test(bareHead[0]!))) {\n    throw new Error(`\"${raw}\" is not a valid npm package name.`);\n  }\n  if (at !== -1 && range.length < 2) throw new Error(`\"${raw}\" has an empty version after \"@\".`);\n  if (subpath && !subpath.split('/').every((s) => /^[A-Za-z0-9_][\\w.-]*$/.test(s))) {\n    throw new Error(`\"${raw}\" is not a valid package subpath (directory names only, no \"..\").`);\n  }\n\n  if (range && !INSTALL_SPEC_RE.test(`${packageName}${range}`)) {\n    throw new Error(`\"${raw}\" has a version npm install cannot take as one argument (no spaces; use e.g. ^1.2.0).`);\n  }\n\n  return {\n    kind: 'npm',\n    installSpec: `${packageName}${range}`,\n    packageName,\n    ...(subpath ? { subpath } : {}),\n  };\n}\n"]}

package/dist/lib/pkg.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+// dist/lib/pkg.js -> ../../package.json resolves to the package root.
+export const pkg = require('../../package.json');
+//# sourceMappingURL=pkg.js.map

package/dist/lib/pkg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkg.js","sourceRoot":"","sources":["../../src/lib/pkg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAQ/C,sEAAsE;AACtE,MAAM,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC,oBAAoB,CAAgB,CAAC","sourcesContent":["import { createRequire } from 'node:module';\n\nconst require = createRequire(import.meta.url);\n\ninterface PackageJson {\n  name: string;\n  version: string;\n  description?: string;\n}\n\n// dist/lib/pkg.js -> ../../package.json resolves to the package root.\nexport const pkg = require('../../package.json') as PackageJson;\n"]}

package/dist/lib/plugin-setup.js

@@ -0,0 +1,204 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isMap, isSeq, parseDocument } from 'yaml';
+import { confirm, isCancel, password, text } from '@clack/prompts';
+import { shortName } from './spec.js';
+const SETUP_TYPES = new Set(['string', 'secret', 'boolean', 'json']);
+/** Key segments that would reach `Object.prototype` when the dot-path is applied. */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+/** True for a dot-path whose segments are all non-empty and none is forbidden. */
+function isSafeKey(key) {
+    return key.split('.').every((part) => part !== '' && !FORBIDDEN_SEGMENTS.has(part));
+}
+class PluginSetupError extends Error {
+}
+function fail(message) {
+    throw new PluginSetupError(message);
+}
+/**
+ * Reads and validates the `setup` questions of an app package directory, from
+ * `<pkgDir>/plugin/mdk-plugin.json` if present, else `<pkgDir>/mdk-plugin.json`.
+ * Returns `[]` when the package has no manifest or declares no questions;
+ * throws a `PluginSetupError` naming the offender when the block is malformed,
+ * so a broken manifest surfaces as a skippable warning rather than bad prompts.
+ */
+export function readSetupQuestions(pkgDir) {
+    const manifestPath = [join(pkgDir, 'plugin', 'mdk-plugin.json'), join(pkgDir, 'mdk-plugin.json')].find(existsSync);
+    if (!manifestPath)
+        return [];
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        fail(`${manifestPath} is not valid JSON.`);
+    }
+    const setup = manifest.setup;
+    if (setup == null)
+        return [];
+    if (!Array.isArray(setup))
+        fail(`${manifestPath}: \`setup\` must be an array.`);
+    return setup.map((raw, i) => {
+        const q = raw;
+        if (typeof q?.key !== 'string' || !q.key)
+            fail(`${manifestPath}: setup[${i}].key must be a non-empty string.`);
+        if (!isSafeKey(q.key)) {
+            fail(`${manifestPath}: setup[${i}].key must be a dot-path without empty, __proto__, constructor or prototype segments.`);
+        }
+        if (typeof q.prompt !== 'string' || !q.prompt)
+            fail(`${manifestPath}: setup[${i}].prompt must be a non-empty string.`);
+        const type = q.type ?? 'string';
+        if (typeof type !== 'string' || !SETUP_TYPES.has(type)) {
+            fail(`${manifestPath}: setup[${i}].type must be one of string, secret, boolean, json.`);
+        }
+        return {
+            key: q.key,
+            prompt: q.prompt,
+            type: type,
+            required: q.required === true,
+            default: typeof q.default === 'string' || typeof q.default === 'boolean' ? q.default : undefined,
+        };
+    });
+}
+/**
+ * Asks the declared questions via clack — `string` → text, `secret` → masked
+ * password, `boolean` → confirm, `json` → text validated as JSON and stored
+ * parsed (so structured config like role → permission maps stays structured
+ * in the spec) — and returns answers keyed by dot-path. Empty optional
+ * answers are omitted so the spec stays free of `""` noise and plugin
+ * defaults keep applying.
+ */
+export async function promptSetup(questions, onCancel) {
+    const answers = {};
+    for (const q of questions) {
+        let value;
+        if (q.type === 'boolean') {
+            value = await confirm({ message: q.prompt, initialValue: q.default === true });
+        }
+        else if (q.type === 'json') {
+            value = await text({
+                message: q.prompt,
+                validate: (v) => {
+                    const s = v?.trim();
+                    if (!s)
+                        return q.required ? 'Required.' : undefined;
+                    try {
+                        JSON.parse(s);
+                        return undefined;
+                    }
+                    catch {
+                        return 'Enter valid JSON.';
+                    }
+                },
+                ...(typeof q.default === 'string'
+                    ? { placeholder: q.default, defaultValue: q.default, initialValue: q.default }
+                    : q.required
+                        ? {}
+                        : { placeholder: 'Enter to keep the plugin defaults' }),
+            });
+        }
+        else {
+            const validate = (v) => q.required && !v?.trim() ? 'Required.' : undefined;
+            value =
+                q.type === 'secret'
+                    ? await password({ message: q.prompt, validate })
+                    : await text({
+                        message: q.prompt,
+                        validate,
+                        ...(typeof q.default === 'string'
+                            ? { placeholder: q.default, defaultValue: q.default, initialValue: q.default }
+                            : {}),
+                    });
+        }
+        if (isCancel(value))
+            onCancel();
+        if (q.type === 'boolean') {
+            answers[q.key] = value === true;
+        }
+        else if (q.type === 'json') {
+            const s = typeof value === 'string' ? value.trim() : '';
+            if (s)
+                answers[q.key] = JSON.parse(s);
+        }
+        else if (typeof value === 'string' && value.trim()) {
+            answers[q.key] = value.trim();
+        }
+    }
+    return answers;
+}
+/** Sets each dot-path answer into `config`, creating nested mappings on the way. */
+export function applySetupAnswers(config, answers) {
+    for (const [key, value] of Object.entries(answers)) {
+        if (!isSafeKey(key))
+            throw new PluginSetupError(`Unsafe setup key "${key}".`);
+        const parts = key.split('.');
+        let node = config;
+        for (const part of parts.slice(0, -1)) {
+            if (typeof node[part] !== 'object' || node[part] === null || Array.isArray(node[part])) {
+                node[part] = {};
+            }
+            node = node[part];
+        }
+        node[parts.at(-1)] = value;
+    }
+    return config;
+}
+/**
+ * Writes setup answers into `<projectDir>/mdk.yaml` under the app's own
+ * entry in `spec.apps[].config`, preserving the file's
+ * formatting/comments (edits the parsed document, same as the scaffold's
+ * stack-file update). Used for apps whose manifest only becomes readable
+ * after `npm install` — the spec file is already on disk by then.
+ */
+export function applySetupAnswersToStackFile(projectDir, pluginPkg, answers) {
+    const specPath = resolve(projectDir, 'mdk.yaml');
+    if (!existsSync(specPath))
+        return false;
+    try {
+        const doc = parseDocument(readFileSync(specPath, 'utf8'));
+        const plugins = doc.getIn(['spec', 'apps']);
+        if (!isSeq(plugins))
+            return false;
+        const idx = plugins.items.findIndex((item) => isMap(item) && item.get('package') === pluginPkg);
+        if (idx === -1)
+            return false;
+        for (const [key, value] of Object.entries(answers)) {
+            if (!isSafeKey(key))
+                return false;
+            // createNode so structured answers (json questions) serialize as real
+            // YAML mappings/sequences rather than JS object noise.
+            doc.setIn(['spec', 'apps', idx, 'config', ...key.split('.')], doc.createNode(value));
+        }
+        writeFileSync(specPath, doc.toString(), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Env var holding a plugin's secret setup answer: `MDK_<PLUGIN>_<KEY>`. */
+export function secretEnvName(pluginPkg, key) {
+    const part = (s) => s.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return `MDK_${part(shortName(pluginPkg))}_${part(key)}`;
+}
+/**
+ * Keeps `secret` answers out of `mdk.yaml`, which is meant to be committed:
+ * each one is replaced by a `${MDK_<PLUGIN>_<KEY>}` placeholder (resolved by
+ * `loadStackSpec`) and returned in `env` for the caller to write into the
+ * project's gitignored `.env` (see `writeProjectEnv`).
+ */
+export function externalizeSecrets(pluginPkg, questions, answers) {
+    const out = { ...answers };
+    const env = {};
+    for (const q of questions) {
+        const value = answers[q.key];
+        if (q.type !== 'secret' || typeof value !== 'string')
+            continue;
+        const name = secretEnvName(pluginPkg, q.key);
+        env[name] = value;
+        out[q.key] = `\${${name}}`;
+    }
+    return { answers: out, env };
+}
+export { PluginSetupError };
+//# sourceMappingURL=plugin-setup.js.map

package/dist/lib/plugin-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-setup.js","sourceRoot":"","sources":["../../src/lib/plugin-setup.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { isMap, isSeq, parseDocument } from 'yaml';\nimport { confirm, isCancel, password, text } from '@clack/prompts';\nimport { shortName } from './spec.js';\n\n/**\n * One interactive setup question an app declares in its\n * `mdk-plugin.json` under `setup`. `key` is a dot-path under the app's own\n * `config` block in `spec.apps[]` — delivered to that app's runtime alone,\n * merged over the `config` defaults in its `mdk-app.yaml`.\n */\nexport interface SetupQuestion {\n  key: string;\n  prompt: string;\n  type: 'string' | 'secret' | 'boolean' | 'json';\n  required?: boolean;\n  default?: string | boolean;\n}\n\nconst SETUP_TYPES = new Set(['string', 'secret', 'boolean', 'json']);\n\n/** Key segments that would reach `Object.prototype` when the dot-path is applied. */\nconst FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);\n\n/** True for a dot-path whose segments are all non-empty and none is forbidden. */\nfunction isSafeKey(key: string): boolean {\n  return key.split('.').every((part) => part !== '' && !FORBIDDEN_SEGMENTS.has(part));\n}\n\nclass PluginSetupError extends Error {}\n\nfunction fail(message: string): never {\n  throw new PluginSetupError(message);\n}\n\n/**\n * Reads and validates the `setup` questions of an app package directory, from\n * `<pkgDir>/plugin/mdk-plugin.json` if present, else `<pkgDir>/mdk-plugin.json`.\n * Returns `[]` when the package has no manifest or declares no questions;\n * throws a `PluginSetupError` naming the offender when the block is malformed,\n * so a broken manifest surfaces as a skippable warning rather than bad prompts.\n */\nexport function readSetupQuestions(pkgDir: string): SetupQuestion[] {\n  const manifestPath = [join(pkgDir, 'plugin', 'mdk-plugin.json'), join(pkgDir, 'mdk-plugin.json')].find(existsSync);\n  if (!manifestPath) return [];\n\n  let manifest: Record<string, unknown>;\n  try {\n    manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;\n  } catch {\n    fail(`${manifestPath} is not valid JSON.`);\n  }\n\n  const setup = manifest.setup;\n  if (setup == null) return [];\n  if (!Array.isArray(setup)) fail(`${manifestPath}: \\`setup\\` must be an array.`);\n\n  return setup.map((raw, i) => {\n    const q = raw as Record<string, unknown>;\n    if (typeof q?.key !== 'string' || !q.key) fail(`${manifestPath}: setup[${i}].key must be a non-empty string.`);\n    if (!isSafeKey(q.key)) {\n      fail(`${manifestPath}: setup[${i}].key must be a dot-path without empty, __proto__, constructor or prototype segments.`);\n    }\n    if (typeof q.prompt !== 'string' || !q.prompt) fail(`${manifestPath}: setup[${i}].prompt must be a non-empty string.`);\n    const type = q.type ?? 'string';\n    if (typeof type !== 'string' || !SETUP_TYPES.has(type)) {\n      fail(`${manifestPath}: setup[${i}].type must be one of string, secret, boolean, json.`);\n    }\n    return {\n      key: q.key,\n      prompt: q.prompt,\n      type: type as SetupQuestion['type'],\n      required: q.required === true,\n      default: typeof q.default === 'string' || typeof q.default === 'boolean' ? q.default : undefined,\n    };\n  });\n}\n\n/**\n * Asks the declared questions via clack — `string` → text, `secret` → masked\n * password, `boolean` → confirm, `json` → text validated as JSON and stored\n * parsed (so structured config like role → permission maps stays structured\n * in the spec) — and returns answers keyed by dot-path. Empty optional\n * answers are omitted so the spec stays free of `\"\"` noise and plugin\n * defaults keep applying.\n */\nexport async function promptSetup(\n  questions: SetupQuestion[],\n  onCancel: () => never,\n): Promise<Record<string, unknown>> {\n  const answers: Record<string, unknown> = {};\n  for (const q of questions) {\n    let value: unknown;\n    if (q.type === 'boolean') {\n      value = await confirm({ message: q.prompt, initialValue: q.default === true });\n    } else if (q.type === 'json') {\n      value = await text({\n        message: q.prompt,\n        validate: (v) => {\n          const s = v?.trim();\n          if (!s) return q.required ? 'Required.' : undefined;\n          try {\n            JSON.parse(s);\n            return undefined;\n          } catch {\n            return 'Enter valid JSON.';\n          }\n        },\n        ...(typeof q.default === 'string'\n          ? { placeholder: q.default, defaultValue: q.default, initialValue: q.default }\n          : q.required\n            ? {}\n            : { placeholder: 'Enter to keep the plugin defaults' }),\n      });\n    } else {\n      const validate = (v: string | undefined): string | undefined =>\n        q.required && !v?.trim() ? 'Required.' : undefined;\n      value =\n        q.type === 'secret'\n          ? await password({ message: q.prompt, validate })\n          : await text({\n              message: q.prompt,\n              validate,\n              ...(typeof q.default === 'string'\n                ? { placeholder: q.default, defaultValue: q.default, initialValue: q.default }\n                : {}),\n            });\n    }\n    if (isCancel(value)) onCancel();\n    if (q.type === 'boolean') {\n      answers[q.key] = value === true;\n    } else if (q.type === 'json') {\n      const s = typeof value === 'string' ? value.trim() : '';\n      if (s) answers[q.key] = JSON.parse(s);\n    } else if (typeof value === 'string' && value.trim()) {\n      answers[q.key] = value.trim();\n    }\n  }\n  return answers;\n}\n\n/** Sets each dot-path answer into `config`, creating nested mappings on the way. */\nexport function applySetupAnswers(\n  config: Record<string, unknown>,\n  answers: Record<string, unknown>,\n): Record<string, unknown> {\n  for (const [key, value] of Object.entries(answers)) {\n    if (!isSafeKey(key)) throw new PluginSetupError(`Unsafe setup key \"${key}\".`);\n    const parts = key.split('.');\n    let node = config;\n    for (const part of parts.slice(0, -1)) {\n      if (typeof node[part] !== 'object' || node[part] === null || Array.isArray(node[part])) {\n        node[part] = {};\n      }\n      node = node[part] as Record<string, unknown>;\n    }\n    node[parts.at(-1) as string] = value;\n  }\n  return config;\n}\n\n/**\n * Writes setup answers into `<projectDir>/mdk.yaml` under the app's own\n * entry in `spec.apps[].config`, preserving the file's\n * formatting/comments (edits the parsed document, same as the scaffold's\n * stack-file update). Used for apps whose manifest only becomes readable\n * after `npm install` — the spec file is already on disk by then.\n */\nexport function applySetupAnswersToStackFile(\n  projectDir: string,\n  pluginPkg: string,\n  answers: Record<string, unknown>,\n): boolean {\n  const specPath = resolve(projectDir, 'mdk.yaml');\n  if (!existsSync(specPath)) return false;\n\n  try {\n    const doc = parseDocument(readFileSync(specPath, 'utf8'));\n    const plugins = doc.getIn(['spec', 'apps']);\n    if (!isSeq(plugins)) return false;\n    const idx = plugins.items.findIndex((item) => isMap(item) && item.get('package') === pluginPkg);\n    if (idx === -1) return false;\n\n    for (const [key, value] of Object.entries(answers)) {\n      if (!isSafeKey(key)) return false;\n      // createNode so structured answers (json questions) serialize as real\n      // YAML mappings/sequences rather than JS object noise.\n      doc.setIn(\n        ['spec', 'apps', idx, 'config', ...key.split('.')],\n        doc.createNode(value),\n      );\n    }\n    writeFileSync(specPath, doc.toString(), 'utf8');\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Env var holding a plugin's secret setup answer: `MDK_<PLUGIN>_<KEY>`. */\nexport function secretEnvName(pluginPkg: string, key: string): string {\n  const part = (s: string): string => s.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');\n  return `MDK_${part(shortName(pluginPkg))}_${part(key)}`;\n}\n\n/**\n * Keeps `secret` answers out of `mdk.yaml`, which is meant to be committed:\n * each one is replaced by a `${MDK_<PLUGIN>_<KEY>}` placeholder (resolved by\n * `loadStackSpec`) and returned in `env` for the caller to write into the\n * project's gitignored `.env` (see `writeProjectEnv`).\n */\nexport function externalizeSecrets(\n  pluginPkg: string,\n  questions: SetupQuestion[],\n  answers: Record<string, unknown>,\n): { answers: Record<string, unknown>; env: Record<string, string> } {\n  const out: Record<string, unknown> = { ...answers };\n  const env: Record<string, string> = {};\n  for (const q of questions) {\n    const value = answers[q.key];\n    if (q.type !== 'secret' || typeof value !== 'string') continue;\n    const name = secretEnvName(pluginPkg, q.key);\n    env[name] = value;\n    out[q.key] = `\\${${name}}`;\n  }\n  return { answers: out, env };\n}\n\nexport { PluginSetupError };\n"]}

package/dist/lib/ports.js

@@ -0,0 +1,31 @@
+import { createServer } from 'node:net';
+/** Loopback host every local mock and component binds to unless told otherwise. */
+export const DEFAULT_HOST = '127.0.0.1';
+/**
+ * Whether `port` can be bound on `host` right now, tested by actually binding it
+ * (the only answer the OS will give honestly — scanning `lsof` output would miss
+ * sockets owned by other users and races either way).
+ */
+export function isPortFree(port, host = DEFAULT_HOST) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once('error', () => resolve(false));
+        probe.once('listening', () => probe.close(() => resolve(true)));
+        probe.listen(port, host);
+    });
+}
+/**
+ * First bindable port at or after `start`, skipping any already handed out in
+ * this run. Callers scan a small window — a machine with 200 consecutive busy
+ * ports in this range has a bigger problem than port selection.
+ */
+export async function findFreePort({ start, host = DEFAULT_HOST, taken, limit = 200, }) {
+    for (let port = start; port < start + limit && port <= 65535; port++) {
+        if (taken?.has(port))
+            continue;
+        if (await isPortFree(port, host))
+            return port;
+    }
+    throw new Error(`No free port found in ${start}–${start + limit - 1} on ${host}.`);
+}
+//# sourceMappingURL=ports.js.map

package/dist/lib/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/lib/ports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAI,GAAW,YAAY;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC;AAYD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,KAAK,EACL,IAAI,GAAG,YAAY,EACnB,KAAK,EACL,KAAK,GAAG,GAAG,GACK;IAChB,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACrE,IAAI,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/B,IAAI,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,IAAI,KAAK,GAAG,KAAK,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;AACrF,CAAC","sourcesContent":["import { createServer } from 'node:net';\n\n/** Loopback host every local mock and component binds to unless told otherwise. */\nexport const DEFAULT_HOST = '127.0.0.1';\n\n/**\n * Whether `port` can be bound on `host` right now, tested by actually binding it\n * (the only answer the OS will give honestly — scanning `lsof` output would miss\n * sockets owned by other users and races either way).\n */\nexport function isPortFree(port: number, host: string = DEFAULT_HOST): Promise<boolean> {\n  return new Promise((resolve) => {\n    const probe = createServer();\n    probe.once('error', () => resolve(false));\n    probe.once('listening', () => probe.close(() => resolve(true)));\n    probe.listen(port, host);\n  });\n}\n\nexport interface FreePortOptions {\n  /** First port to try. */\n  start: number;\n  host?: string;\n  /** Ports to treat as taken even if the OS says they are free (already handed out). */\n  taken?: Set<number>;\n  /** How many ports to try before giving up. */\n  limit?: number;\n}\n\n/**\n * First bindable port at or after `start`, skipping any already handed out in\n * this run. Callers scan a small window — a machine with 200 consecutive busy\n * ports in this range has a bigger problem than port selection.\n */\nexport async function findFreePort({\n  start,\n  host = DEFAULT_HOST,\n  taken,\n  limit = 200,\n}: FreePortOptions): Promise<number> {\n  for (let port = start; port < start + limit && port <= 65535; port++) {\n    if (taken?.has(port)) continue;\n    if (await isPortFree(port, host)) return port;\n  }\n  throw new Error(`No free port found in ${start}–${start + limit - 1} on ${host}.`);\n}\n"]}