@tetherto/mdk-cli 0.0.0-stage → 0.12.1

package/dist/lib/project.js

@@ -0,0 +1,297 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+/**
+ * Project scaffolding shared by `mdk onboard` and `mdk create` — the files that
+ * describe the *project* rather than any one component.
+ *
+ * The emitted layout is role-grouped, mirroring MDK's own component model, so a
+ * path in `mdk.yaml` says what it is:
+ *
+ *   mdk.yaml          the stack spec
+ *   package.json      private root manifest (no `workspaces` key — path-backed
+ *                     packages link via relative `file:` deps so `npm install`
+ *                     works inside the project directory)
+ *   workers/<name>/   worker plugins   (mdk create worker)
+ *   apps/<name>/      apps             (mdk create app)
+ *   apps/dashboard/   the UI dashboard (mdk create dashboard)
+ *   .mdk/             runtime state written by `mdk run` (gitignored)
+ */
+/** Component directories, relative to the project root. */
+export const DIRS = {
+    workers: 'workers',
+    apps: 'apps',
+    /** Canonical dashboard location — a stable path, unlike the app's package name. */
+    dashboard: join('apps', 'dashboard'),
+};
+/**
+ * Historical workspace globs (`workers/*`, `plugins/*`). Kept for reading
+ * pre-existing manifests that still declare them (`isWorkspaceMember`); new
+ * projects never write a `workspaces` key — local scaffolds use `file:` deps.
+ */
+export const WORKSPACES = [`${DIRS.workers}/*`, 'plugins/*'];
+/** Coerces a stack name into a valid npm package name. */
+function npmName(name) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[._-]+|[-._]+$/g, '');
+    return slug || 'mdk-stack';
+}
+/**
+ * Ensures the project has a private root `package.json`. Creates one if absent
+ * (no `workspaces` key — local packages are linked via `file:` dependencies).
+ * An existing manifest is never modified (name, deps, scripts, or workspaces).
+ */
+export function ensureProjectManifest(targetDir, stackName) {
+    const path = join(targetDir, 'package.json');
+    if (!existsSync(path)) {
+        const manifest = {
+            name: npmName(stackName),
+            version: '0.1.0',
+            private: true,
+            scripts: { dev: 'mdk run' },
+        };
+        writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+        return 'created';
+    }
+    // Existing manifest is the user's — never overwrite it, and never inject workspaces.
+    return 'present';
+}
+/** The project's declared workspace globs (empty when it is not a workspace root). */
+function readWorkspaces(targetDir) {
+    const path = join(targetDir, 'package.json');
+    if (!existsSync(path))
+        return [];
+    try {
+        const pkg = JSON.parse(readFileSync(path, 'utf8'));
+        return Array.isArray(pkg.workspaces) ? pkg.workspaces.filter((w) => typeof w === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * True when `packageDir` is covered by one of the project's workspace globs —
+ * i.e. a root `npm install` would actually install it. Only such components may
+ * be installed from the root; anything else (the dashboard, which is
+ * intentionally outside the workspaces) has to install in its own directory.
+ */
+export function isWorkspaceMember(targetDir, packageDir) {
+    const globs = readWorkspaces(targetDir);
+    if (!globs.length)
+        return false;
+    const rel = relative(resolve(targetDir), resolve(packageDir));
+    if (!rel || rel.startsWith('..'))
+        return false;
+    const segments = rel.split(sep);
+    return globs.some((glob) => {
+        const parts = glob.split('/');
+        return (parts.length === segments.length && parts.every((p, i) => p === '*' || p === segments[i]));
+    });
+}
+/**
+ * True when the project root already declares a `file:` dependency — in
+ * either `dependencies` or `devDependencies` — that points at `packageDir`, so
+ * `npm install` must run at the project root to create the symlink the
+ * runtime resolves from `node_modules`.
+ */
+export function isFileLinkedFromProject(targetDir, packageDir) {
+    const path = join(targetDir, 'package.json');
+    if (!existsSync(path))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(path, 'utf8'));
+        const deps = { ...pkg.devDependencies, ...pkg.dependencies };
+        const absPackage = resolve(packageDir);
+        return Object.values(deps).some((spec) => {
+            if (!spec.startsWith('file:'))
+                return false;
+            return resolve(targetDir, spec.slice('file:'.length)) === absPackage;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** Sets one `dependencies` entry in the project root manifest, if not already set. */
+function setDependency(targetDir, packageName, versionSpec) {
+    const path = join(targetDir, 'package.json');
+    if (!existsSync(path))
+        throw new Error('no package.json');
+    const pkg = JSON.parse(readFileSync(path, 'utf8'));
+    if (!pkg.dependencies)
+        pkg.dependencies = {};
+    if (pkg.dependencies[packageName] === versionSpec)
+        return;
+    pkg.dependencies[packageName] = versionSpec;
+    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
+/**
+ * Declares a `file:`-linked dependency pointing at `absPath`, written relative
+ * to `targetDir`. Works for packages inside the project folder and for bundled
+ * monorepo catalog checkouts outside it — never appends to a `workspaces`
+ * array, and never writes bare `*` (that hits the registry when the project is
+ * not a monorepo workspace member). `npm install` resolves the relative
+ * `file:` specifier against the project root and symlinks it into
+ * `node_modules/<packageName>`.
+ */
+export function addFileDependency(targetDir, packageName, absPath) {
+    const target = resolve(absPath);
+    const rel = relative(resolve(targetDir), target);
+    // `path.relative()` returns an absolute path when `targetDir` and `absPath`
+    // are on different drives (Windows only) — fall back to the absolute path
+    // rather than writing a `file:./C:/...` spec, which npm resolves under the
+    // project dir and 404s.
+    const posix = (isAbsolute(rel) ? target : rel).split(sep).join('/');
+    const spec = isAbsolute(rel) || posix.startsWith('.') ? posix : `./${posix}`;
+    setDependency(targetDir, packageName, `file:${spec}`);
+}
+/**
+ * The stack name from `<dir>/mdk.yaml` (falling back to the directory name), or
+ * null when there is no spec — i.e. when the directory is not an MDK project and
+ * nothing should be scaffolded into it.
+ */
+export function readStackName(targetDir) {
+    const specPath = join(targetDir, 'mdk.yaml');
+    if (!existsSync(specPath))
+        return null;
+    try {
+        const doc = parseYaml(readFileSync(specPath, 'utf8'));
+        const name = doc?.metadata?.name?.trim();
+        if (name)
+            return name;
+    }
+    catch {
+        /* fall through to the directory name */
+    }
+    return basename(resolve(targetDir));
+}
+const GITIGNORE_HEADER = '# MDK';
+const GITIGNORE_BLOCK = [
+    `${GITIGNORE_HEADER} runtime state — kernel/gateway stores, worker DBs, discovery keys`,
+    '.mdk/',
+    '',
+    '# Dependencies & build output',
+    'node_modules/',
+    'dist/',
+    'coverage/',
+    '.vite/',
+    '*.tsbuildinfo',
+    '',
+    '# Local environment (commit .env.example instead)',
+    '.env',
+    '.env.local',
+    '*.log',
+    '',
+].join('\n');
+/**
+ * Ensures the project has a `.gitignore` covering MDK runtime state and the
+ * build output of the components it scaffolds. Creates one if absent; if a
+ * `.gitignore` already exists without the MDK block, appends it (never clobbers
+ * user content).
+ */
+export function ensureProjectGitignore(targetDir) {
+    const path = join(targetDir, '.gitignore');
+    if (!existsSync(path)) {
+        writeFileSync(path, GITIGNORE_BLOCK, 'utf8');
+        return 'created';
+    }
+    const current = readFileSync(path, 'utf8');
+    if (current.includes(GITIGNORE_HEADER) || current.includes('.mdk/')) {
+        // `.env` holds secret plugin-setup answers, so it must be ignored even when
+        // an older or hand-edited MDK block left it out.
+        if (/^\/?\.env\s*$/m.test(current))
+            return 'present';
+        appendFileSync(path, `${current.endsWith('\n') ? '' : '\n'}.env\n`, 'utf8');
+        return 'updated';
+    }
+    appendFileSync(path, `${current.endsWith('\n') ? '' : '\n'}\n${GITIGNORE_BLOCK}`, 'utf8');
+    return 'updated';
+}
+function runSection({ workerNames }) {
+    const workers = workerNames.length
+        ? workerNames.map((name) => `mdk run worker ${name}`)
+        : ['mdk run worker <name>'];
+    return [
+        '```bash',
+        'npm install   # once, links workers/ and apps/',
+        'mdk run       # boots Kernel, workers, apps and Gateway together',
+        '```',
+        '',
+        'Or run each component in its own terminal:',
+        '',
+        '```bash',
+        'mdk run kernel',
+        'mdk run gateway',
+        ...workers,
+        '```',
+    ].join('\n');
+}
+/**
+ * Writes a project README describing the emitted layout and how to run the
+ * stack. Never overwrites an existing README.
+ */
+export function ensureProjectReadme(targetDir, opts) {
+    const path = join(targetDir, 'README.md');
+    if (existsSync(path))
+        return 'present';
+    const dashboard = opts.dashboardDir
+        ? [
+            '## Dashboard',
+            '',
+            '```bash',
+            `cd ${opts.dashboardDir}`,
+            'npm install',
+            'npm run dev',
+            '```',
+            '',
+            'It proxies `/auth`, `/api` and `/pub` to the Gateway, so start the stack first.',
+            '',
+            '',
+        ].join('\n')
+        : '';
+    const content = `# ${opts.stackName}
+
+An MDK stack — a Kernel, a Gateway and its Workers — described declaratively in
+\`mdk.yaml\`. Edit that file to change ports, apps, workers or the
+devices each worker manages.
+
+## Layout
+
+\`\`\`
+mdk.yaml           the stack spec: ports, apps, workers, devices
+workers/<name>/    worker plugins — device contract, handlers and a mock device
+apps/<name>/       apps — HTTP aggregation endpoints served through the Gateway
+apps/dashboard/    the UI dashboard (Vite app)
+.mdk/              runtime state written by \`mdk run\` — disposable, gitignored
+\`\`\`
+
+Workers, apps and bundled monorepo catalog packages are linked with relative
+\`file:\` dependencies (no \`workspaces\` key). One \`npm install\` at the project
+root wires them up so \`mdk run\` can resolve them. Component directories
+appear as you add components.
+
+## Run it
+
+${runSection(opts)}
+
+## Add components
+
+\`\`\`bash
+mdk create worker <name>      # scaffolds workers/<name> and registers it in mdk.yaml
+mdk create app <name>         # scaffolds apps/<name> and registers it in mdk.yaml
+mdk create dashboard          # scaffolds apps/dashboard
+\`\`\`
+
+${dashboard}## Runtime state
+
+\`.mdk/\` holds the Kernel and Gateway stores, each worker's database and identity
+keys, and the local discovery keys. Delete it to reset the stack — every
+component then comes back with a new identity; it is never committed.
+`;
+    writeFileSync(path, content, 'utf8');
+    return 'created';
+}
+//# sourceMappingURL=project.js.map

package/dist/lib/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/lib/project.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\n\n/**\n * Project scaffolding shared by `mdk onboard` and `mdk create` — the files that\n * describe the *project* rather than any one component.\n *\n * The emitted layout is role-grouped, mirroring MDK's own component model, so a\n * path in `mdk.yaml` says what it is:\n *\n *   mdk.yaml          the stack spec\n *   package.json      private root manifest (no `workspaces` key — path-backed\n *                     packages link via relative `file:` deps so `npm install`\n *                     works inside the project directory)\n *   workers/<name>/   worker plugins   (mdk create worker)\n *   apps/<name>/      apps             (mdk create app)\n *   apps/dashboard/   the UI dashboard (mdk create dashboard)\n *   .mdk/             runtime state written by `mdk run` (gitignored)\n */\n\n/** Component directories, relative to the project root. */\nexport const DIRS = {\n  workers: 'workers',\n  apps: 'apps',\n  /** Canonical dashboard location — a stable path, unlike the app's package name. */\n  dashboard: join('apps', 'dashboard'),\n} as const;\n\n/**\n * Historical workspace globs (`workers/*`, `plugins/*`). Kept for reading\n * pre-existing manifests that still declare them (`isWorkspaceMember`); new\n * projects never write a `workspaces` key — local scaffolds use `file:` deps.\n */\nexport const WORKSPACES = [`${DIRS.workers}/*`, 'plugins/*'];\n\nexport type FileAction = 'created' | 'updated' | 'present';\n\n/** Coerces a stack name into a valid npm package name. */\nfunction npmName(name: string): string {\n  const slug = name\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, '-')\n    .replace(/^[._-]+|[-._]+$/g, '');\n  return slug || 'mdk-stack';\n}\n\n/**\n * Ensures the project has a private root `package.json`. Creates one if absent\n * (no `workspaces` key — local packages are linked via `file:` dependencies).\n * An existing manifest is never modified (name, deps, scripts, or workspaces).\n */\nexport function ensureProjectManifest(targetDir: string, stackName: string): FileAction {\n  const path = join(targetDir, 'package.json');\n\n  if (!existsSync(path)) {\n    const manifest = {\n      name: npmName(stackName),\n      version: '0.1.0',\n      private: true,\n      scripts: { dev: 'mdk run' },\n    };\n    writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\\n`, 'utf8');\n    return 'created';\n  }\n\n  // Existing manifest is the user's — never overwrite it, and never inject workspaces.\n  return 'present';\n}\n\n/** The project's declared workspace globs (empty when it is not a workspace root). */\nfunction readWorkspaces(targetDir: string): string[] {\n  const path = join(targetDir, 'package.json');\n  if (!existsSync(path)) return [];\n  try {\n    const pkg = JSON.parse(readFileSync(path, 'utf8')) as { workspaces?: unknown };\n    return Array.isArray(pkg.workspaces) ? pkg.workspaces.filter((w) => typeof w === 'string') : [];\n  } catch {\n    return [];\n  }\n}\n\n/**\n * True when `packageDir` is covered by one of the project's workspace globs —\n * i.e. a root `npm install` would actually install it. Only such components may\n * be installed from the root; anything else (the dashboard, which is\n * intentionally outside the workspaces) has to install in its own directory.\n */\nexport function isWorkspaceMember(targetDir: string, packageDir: string): boolean {\n  const globs = readWorkspaces(targetDir);\n  if (!globs.length) return false;\n\n  const rel = relative(resolve(targetDir), resolve(packageDir));\n  if (!rel || rel.startsWith('..')) return false;\n  const segments = rel.split(sep);\n\n  return globs.some((glob) => {\n    const parts = glob.split('/');\n    return (\n      parts.length === segments.length && parts.every((p, i) => p === '*' || p === segments[i])\n    );\n  });\n}\n\n/**\n * True when the project root already declares a `file:` dependency — in\n * either `dependencies` or `devDependencies` — that points at `packageDir`, so\n * `npm install` must run at the project root to create the symlink the\n * runtime resolves from `node_modules`.\n */\nexport function isFileLinkedFromProject(targetDir: string, packageDir: string): boolean {\n  const path = join(targetDir, 'package.json');\n  if (!existsSync(path)) return false;\n  try {\n    const pkg = JSON.parse(readFileSync(path, 'utf8')) as {\n      dependencies?: Record<string, string>;\n      devDependencies?: Record<string, string>;\n    };\n    const deps = { ...pkg.devDependencies, ...pkg.dependencies };\n    const absPackage = resolve(packageDir);\n    return Object.values(deps).some((spec) => {\n      if (!spec.startsWith('file:')) return false;\n      return resolve(targetDir, spec.slice('file:'.length)) === absPackage;\n    });\n  } catch {\n    return false;\n  }\n}\n\n/** Sets one `dependencies` entry in the project root manifest, if not already set. */\nfunction setDependency(targetDir: string, packageName: string, versionSpec: string): void {\n  const path = join(targetDir, 'package.json');\n  if (!existsSync(path)) throw new Error('no package.json');\n\n  const pkg = JSON.parse(readFileSync(path, 'utf8')) as {\n    dependencies?: Record<string, string>;\n  };\n  if (!pkg.dependencies) pkg.dependencies = {};\n  if (pkg.dependencies[packageName] === versionSpec) return;\n  pkg.dependencies[packageName] = versionSpec;\n  writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\\n`, 'utf8');\n}\n\n/**\n * Declares a `file:`-linked dependency pointing at `absPath`, written relative\n * to `targetDir`. Works for packages inside the project folder and for bundled\n * monorepo catalog checkouts outside it — never appends to a `workspaces`\n * array, and never writes bare `*` (that hits the registry when the project is\n * not a monorepo workspace member). `npm install` resolves the relative\n * `file:` specifier against the project root and symlinks it into\n * `node_modules/<packageName>`.\n */\nexport function addFileDependency(targetDir: string, packageName: string, absPath: string): void {\n  const target = resolve(absPath);\n  const rel = relative(resolve(targetDir), target);\n  // `path.relative()` returns an absolute path when `targetDir` and `absPath`\n  // are on different drives (Windows only) — fall back to the absolute path\n  // rather than writing a `file:./C:/...` spec, which npm resolves under the\n  // project dir and 404s.\n  const posix = (isAbsolute(rel) ? target : rel).split(sep).join('/');\n  const spec = isAbsolute(rel) || posix.startsWith('.') ? posix : `./${posix}`;\n  setDependency(targetDir, packageName, `file:${spec}`);\n}\n\n/**\n * The stack name from `<dir>/mdk.yaml` (falling back to the directory name), or\n * null when there is no spec — i.e. when the directory is not an MDK project and\n * nothing should be scaffolded into it.\n */\nexport function readStackName(targetDir: string): string | null {\n  const specPath = join(targetDir, 'mdk.yaml');\n  if (!existsSync(specPath)) return null;\n  try {\n    const doc = parseYaml(readFileSync(specPath, 'utf8')) as { metadata?: { name?: string } };\n    const name = doc?.metadata?.name?.trim();\n    if (name) return name;\n  } catch {\n    /* fall through to the directory name */\n  }\n  return basename(resolve(targetDir));\n}\n\nconst GITIGNORE_HEADER = '# MDK';\nconst GITIGNORE_BLOCK = [\n  `${GITIGNORE_HEADER} runtime state — kernel/gateway stores, worker DBs, discovery keys`,\n  '.mdk/',\n  '',\n  '# Dependencies & build output',\n  'node_modules/',\n  'dist/',\n  'coverage/',\n  '.vite/',\n  '*.tsbuildinfo',\n  '',\n  '# Local environment (commit .env.example instead)',\n  '.env',\n  '.env.local',\n  '*.log',\n  '',\n].join('\\n');\n\n/**\n * Ensures the project has a `.gitignore` covering MDK runtime state and the\n * build output of the components it scaffolds. Creates one if absent; if a\n * `.gitignore` already exists without the MDK block, appends it (never clobbers\n * user content).\n */\nexport function ensureProjectGitignore(targetDir: string): FileAction {\n  const path = join(targetDir, '.gitignore');\n  if (!existsSync(path)) {\n    writeFileSync(path, GITIGNORE_BLOCK, 'utf8');\n    return 'created';\n  }\n  const current = readFileSync(path, 'utf8');\n  if (current.includes(GITIGNORE_HEADER) || current.includes('.mdk/')) {\n    // `.env` holds secret plugin-setup answers, so it must be ignored even when\n    // an older or hand-edited MDK block left it out.\n    if (/^\\/?\\.env\\s*$/m.test(current)) return 'present';\n    appendFileSync(path, `${current.endsWith('\\n') ? '' : '\\n'}.env\\n`, 'utf8');\n    return 'updated';\n  }\n  appendFileSync(path, `${current.endsWith('\\n') ? '' : '\\n'}\\n${GITIGNORE_BLOCK}`, 'utf8');\n  return 'updated';\n}\n\nexport interface ReadmeOptions {\n  stackName: string;\n  /** Worker names from the spec, for the per-component run commands. */\n  workerNames: string[];\n  /** Dashboard path relative to the project root, when one was scaffolded. */\n  dashboardDir?: string;\n}\n\nfunction runSection({ workerNames }: ReadmeOptions): string {\n  const workers = workerNames.length\n    ? workerNames.map((name) => `mdk run worker ${name}`)\n    : ['mdk run worker <name>'];\n  return [\n    '```bash',\n    'npm install   # once, links workers/ and apps/',\n    'mdk run       # boots Kernel, workers, apps and Gateway together',\n    '```',\n    '',\n    'Or run each component in its own terminal:',\n    '',\n    '```bash',\n    'mdk run kernel',\n    'mdk run gateway',\n    ...workers,\n    '```',\n  ].join('\\n');\n}\n\n/**\n * Writes a project README describing the emitted layout and how to run the\n * stack. Never overwrites an existing README.\n */\nexport function ensureProjectReadme(targetDir: string, opts: ReadmeOptions): FileAction {\n  const path = join(targetDir, 'README.md');\n  if (existsSync(path)) return 'present';\n\n  const dashboard = opts.dashboardDir\n    ? [\n        '## Dashboard',\n        '',\n        '```bash',\n        `cd ${opts.dashboardDir}`,\n        'npm install',\n        'npm run dev',\n        '```',\n        '',\n        'It proxies `/auth`, `/api` and `/pub` to the Gateway, so start the stack first.',\n        '',\n        '',\n      ].join('\\n')\n    : '';\n\n  const content = `# ${opts.stackName}\n\nAn MDK stack — a Kernel, a Gateway and its Workers — described declaratively in\n\\`mdk.yaml\\`. Edit that file to change ports, apps, workers or the\ndevices each worker manages.\n\n## Layout\n\n\\`\\`\\`\nmdk.yaml           the stack spec: ports, apps, workers, devices\nworkers/<name>/    worker plugins — device contract, handlers and a mock device\napps/<name>/       apps — HTTP aggregation endpoints served through the Gateway\napps/dashboard/    the UI dashboard (Vite app)\n.mdk/              runtime state written by \\`mdk run\\` — disposable, gitignored\n\\`\\`\\`\n\nWorkers, apps and bundled monorepo catalog packages are linked with relative\n\\`file:\\` dependencies (no \\`workspaces\\` key). One \\`npm install\\` at the project\nroot wires them up so \\`mdk run\\` can resolve them. Component directories\nappear as you add components.\n\n## Run it\n\n${runSection(opts)}\n\n## Add components\n\n\\`\\`\\`bash\nmdk create worker <name>      # scaffolds workers/<name> and registers it in mdk.yaml\nmdk create app <name>         # scaffolds apps/<name> and registers it in mdk.yaml\nmdk create dashboard          # scaffolds apps/dashboard\n\\`\\`\\`\n\n${dashboard}## Runtime state\n\n\\`.mdk/\\` holds the Kernel and Gateway stores, each worker's database and identity\nkeys, and the local discovery keys. Delete it to reset the stack — every\ncomponent then comes back with a new identity; it is never committed.\n`;\n\n  writeFileSync(path, content, 'utf8');\n  return 'created';\n}\n"]}

package/dist/lib/run-lock.js

@@ -0,0 +1,188 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Absolute path of a component's lock file. */
+export function runLockFile(projectDir, component) {
+    if (component.name !== undefined && !/^[a-z0-9][a-z0-9._-]*$/.test(component.name)) {
+        throw new Error(`Invalid ${component.kind} name "${component.name}".`);
+    }
+    const file = component.name ? `${component.kind}-${component.name}.pid` : `${component.kind}.pid`;
+    return join(resolve(projectDir), '.mdk', 'run', file);
+}
+/**
+ * Where `mdk run` records the pid of a supervised app's runtime process. The run
+ * lock names the supervisor, which outlives a child that crashed and is waiting
+ * to restart; this file only exists while a child is up.
+ */
+export function appChildFile(projectDir, name) {
+    return runLockFile(projectDir, { kind: 'app', name }).replace(/\.pid$/, '.child');
+}
+/** The pid in an app's child file: undefined without one (the app runs in-process). */
+export function appChildPid(projectDir, name) {
+    try {
+        return Number(readFileSync(appChildFile(projectDir, name), 'utf8').trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+function label(component) {
+    return component.name ? `${component.kind} "${component.name}"` : `The ${component.kind}`;
+}
+/** True when `pid` is a live process (EPERM still means it exists). */
+export function isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The live pid holding a component's lock, or null when it is free or stale. */
+export function lockHolder(projectDir, component) {
+    let pid;
+    try {
+        pid = Number(readFileSync(runLockFile(projectDir, component), 'utf8').trim());
+    }
+    catch {
+        return null;
+    }
+    return isAlive(pid) ? pid : null;
+}
+function capitalize(text) {
+    return text[0].toUpperCase() + text.slice(1);
+}
+/** Lock files this process owns; removed when it exits. */
+const owned = new Set();
+let exitHookInstalled = false;
+function releaseFile(file) {
+    owned.delete(file);
+    try {
+        if (readFileSync(file, 'utf8').trim() === String(process.pid))
+            unlinkSync(file);
+    }
+    catch {
+        /* already gone */
+    }
+}
+function releaseAll() {
+    for (const file of [...owned])
+        releaseFile(file);
+}
+function alreadyRunning(component, file, holder) {
+    return new Error(`${capitalize(label(component))} is already running for this project (pid ${holder}).\n` +
+        `Stop it first, or remove ${file} if that process is not an MDK component.`);
+}
+const isEexist = (error) => error.code === 'EEXIST';
+/** Blocks the thread for `ms` (lock acquisition is synchronous). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const TAKEOVER_TRIES = 100;
+const TAKEOVER_WAIT_MS = 20;
+/**
+ * Replaces a stale lock under a `<lock>.takeover` guard, so two processes that
+ * both found it stale cannot both pass the check and one delete the lock the
+ * other just took. A guard whose process is gone is cleared.
+ */
+function takeOver(projectDir, component, file) {
+    const guard = `${file}.takeover`;
+    for (let tries = 0;; tries++) {
+        try {
+            writeFileSync(guard, String(process.pid), { flag: 'wx' });
+            break;
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            let guardPid = 0;
+            try {
+                guardPid = Number(readFileSync(guard, 'utf8').trim());
+            }
+            catch {
+                continue; // released meanwhile
+            }
+            if (!isAlive(guardPid)) {
+                try {
+                    unlinkSync(guard);
+                }
+                catch {
+                    /* cleared by another process */
+                }
+                continue;
+            }
+            if (tries >= TAKEOVER_TRIES) {
+                throw new Error(`${capitalize(label(component))} is being started by another process (pid ${guardPid}).`);
+            }
+            sleepSync(TAKEOVER_WAIT_MS);
+        }
+    }
+    try {
+        const holder = lockHolder(projectDir, component);
+        if (holder !== null && holder !== process.pid)
+            throw alreadyRunning(component, file, holder);
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            /* already gone */
+        }
+        try {
+            writeFileSync(file, String(process.pid), { flag: 'wx' });
+        }
+        catch (error) {
+            // A process that found no lock at all took it first.
+            if (!isEexist(error))
+                throw error;
+            throw alreadyRunning(component, file, lockHolder(projectDir, component) ?? 0);
+        }
+    }
+    finally {
+        try {
+            unlinkSync(guard);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/**
+ * Takes the run locks for every component this process is about to start, or
+ * throws naming the one already running. All or nothing: on a conflict the
+ * locks taken so far are released. The locks are dropped when the process exits.
+ */
+export function acquireRunLocks(projectDir, components) {
+    const taken = [];
+    const release = () => {
+        for (const file of taken.splice(0))
+            releaseFile(file);
+    };
+    try {
+        for (const component of components) {
+            const file = runLockFile(projectDir, component);
+            mkdirSync(dirname(file), { recursive: true });
+            try {
+                writeFileSync(file, String(process.pid), { flag: 'wx' });
+            }
+            catch (error) {
+                if (!isEexist(error))
+                    throw error;
+                takeOver(projectDir, component, file);
+            }
+            taken.push(file);
+            owned.add(file);
+        }
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+    if (!exitHookInstalled) {
+        exitHookInstalled = true;
+        process.once('exit', releaseAll);
+    }
+    return { release };
+}
+//# sourceMappingURL=run-lock.js.map

package/dist/lib/run-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-lock.js","sourceRoot":"","sources":["../../src/lib/run-lock.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\nimport { dirname, join, resolve } from 'node:path';\n\n/**\n * One running copy per component and project. Two copies of a worker or app share\n * its identity keys and store, so the second one takes over the first one's DHT\n * key and the first goes unreachable once either stops; two Kernels fight over\n * the store lock. A `.mdk/run/<component>.pid` file names the process that owns\n * the component; a stale file (its process gone) is taken over.\n */\n\n/** A component that holds a run lock: `kernel`, `worker <name>` or `app <name>`. */\nexport interface RunComponent {\n  kind: 'kernel' | 'worker' | 'app';\n  name?: string;\n}\n\n/** Absolute path of a component's lock file. */\nexport function runLockFile(projectDir: string, component: RunComponent): string {\n  if (component.name !== undefined && !/^[a-z0-9][a-z0-9._-]*$/.test(component.name)) {\n    throw new Error(`Invalid ${component.kind} name \"${component.name}\".`);\n  }\n  const file = component.name ? `${component.kind}-${component.name}.pid` : `${component.kind}.pid`;\n  return join(resolve(projectDir), '.mdk', 'run', file);\n}\n\n/**\n * Where `mdk run` records the pid of a supervised app's runtime process. The run\n * lock names the supervisor, which outlives a child that crashed and is waiting\n * to restart; this file only exists while a child is up.\n */\nexport function appChildFile(projectDir: string, name: string): string {\n  return runLockFile(projectDir, { kind: 'app', name }).replace(/\\.pid$/, '.child');\n}\n\n/** The pid in an app's child file: undefined without one (the app runs in-process). */\nexport function appChildPid(projectDir: string, name: string): number | undefined {\n  try {\n    return Number(readFileSync(appChildFile(projectDir, name), 'utf8').trim());\n  } catch {\n    return undefined;\n  }\n}\n\nfunction label(component: RunComponent): string {\n  return component.name ? `${component.kind} \"${component.name}\"` : `The ${component.kind}`;\n}\n\n/** True when `pid` is a live process (EPERM still means it exists). */\nexport function isAlive(pid: number): boolean {\n  if (!Number.isInteger(pid) || pid <= 0) return false;\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (error) {\n    return (error as NodeJS.ErrnoException).code === 'EPERM';\n  }\n}\n\n/** The live pid holding a component's lock, or null when it is free or stale. */\nexport function lockHolder(projectDir: string, component: RunComponent): number | null {\n  let pid: number;\n  try {\n    pid = Number(readFileSync(runLockFile(projectDir, component), 'utf8').trim());\n  } catch {\n    return null;\n  }\n  return isAlive(pid) ? pid : null;\n}\n\nfunction capitalize(text: string): string {\n  return text[0]!.toUpperCase() + text.slice(1);\n}\n\n/** Lock files this process owns; removed when it exits. */\nconst owned = new Set<string>();\nlet exitHookInstalled = false;\n\nfunction releaseFile(file: string): void {\n  owned.delete(file);\n  try {\n    if (readFileSync(file, 'utf8').trim() === String(process.pid)) unlinkSync(file);\n  } catch {\n    /* already gone */\n  }\n}\n\nfunction releaseAll(): void {\n  for (const file of [...owned]) releaseFile(file);\n}\n\nfunction alreadyRunning(component: RunComponent, file: string, holder: number): Error {\n  return new Error(\n    `${capitalize(label(component))} is already running for this project (pid ${holder}).\\n` +\n      `Stop it first, or remove ${file} if that process is not an MDK component.`,\n  );\n}\n\nconst isEexist = (error: unknown): boolean => (error as NodeJS.ErrnoException).code === 'EEXIST';\n\n/** Blocks the thread for `ms` (lock acquisition is synchronous). */\nfunction sleepSync(ms: number): void {\n  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\nconst TAKEOVER_TRIES = 100;\nconst TAKEOVER_WAIT_MS = 20;\n\n/**\n * Replaces a stale lock under a `<lock>.takeover` guard, so two processes that\n * both found it stale cannot both pass the check and one delete the lock the\n * other just took. A guard whose process is gone is cleared.\n */\nfunction takeOver(projectDir: string, component: RunComponent, file: string): void {\n  const guard = `${file}.takeover`;\n  for (let tries = 0; ; tries++) {\n    try {\n      writeFileSync(guard, String(process.pid), { flag: 'wx' });\n      break;\n    } catch (error) {\n      if (!isEexist(error)) throw error;\n      let guardPid = 0;\n      try {\n        guardPid = Number(readFileSync(guard, 'utf8').trim());\n      } catch {\n        continue; // released meanwhile\n      }\n      if (!isAlive(guardPid)) {\n        try {\n          unlinkSync(guard);\n        } catch {\n          /* cleared by another process */\n        }\n        continue;\n      }\n      if (tries >= TAKEOVER_TRIES) {\n        throw new Error(`${capitalize(label(component))} is being started by another process (pid ${guardPid}).`);\n      }\n      sleepSync(TAKEOVER_WAIT_MS);\n    }\n  }\n\n  try {\n    const holder = lockHolder(projectDir, component);\n    if (holder !== null && holder !== process.pid) throw alreadyRunning(component, file, holder);\n    try {\n      unlinkSync(file);\n    } catch {\n      /* already gone */\n    }\n    try {\n      writeFileSync(file, String(process.pid), { flag: 'wx' });\n    } catch (error) {\n      // A process that found no lock at all took it first.\n      if (!isEexist(error)) throw error;\n      throw alreadyRunning(component, file, lockHolder(projectDir, component) ?? 0);\n    }\n  } finally {\n    try {\n      unlinkSync(guard);\n    } catch {\n      /* already gone */\n    }\n  }\n}\n\n/**\n * Takes the run locks for every component this process is about to start, or\n * throws naming the one already running. All or nothing: on a conflict the\n * locks taken so far are released. The locks are dropped when the process exits.\n */\nexport function acquireRunLocks(projectDir: string, components: RunComponent[]): { release(): void } {\n  const taken: string[] = [];\n  const release = (): void => {\n    for (const file of taken.splice(0)) releaseFile(file);\n  };\n\n  try {\n    for (const component of components) {\n      const file = runLockFile(projectDir, component);\n      mkdirSync(dirname(file), { recursive: true });\n      try {\n        writeFileSync(file, String(process.pid), { flag: 'wx' });\n      } catch (error) {\n        if (!isEexist(error)) throw error;\n        takeOver(projectDir, component, file);\n      }\n      taken.push(file);\n      owned.add(file);\n    }\n  } catch (error) {\n    release();\n    throw error;\n  }\n\n  if (!exitHookInstalled) {\n    exitHookInstalled = true;\n    process.once('exit', releaseAll);\n  }\n  return { release };\n}\n"]}