@ninedeploy/sdk 0.10.5 → 0.16.0

package/src/manifest.ts

@@ -0,0 +1,414 @@
+import yaml from 'js-yaml';
+import {
+  ninedeployManifest,
+  recommendedRuntimeVersion,
+  type NinedeployManifest,
+} from '@ninedeploy/schemas';
+
+/**
+ * Parse a raw `.ninedeploy` YAML string into a typed object.
+ *
+ * This is the SDK-level counterpart of the server's loader (`@ninedeploy/server`
+ * `ninedeployManifest.ts`): it does the same YAML → Zod step but skips the
+ * filesystem and secret-scan concerns that only matter at deploy time. The
+ * CLI and any external tool that wants to validate a manifest without
+ * calling the server go through here.
+ *
+ * Throws a `ManifestParseError` for malformed YAML and a
+ * `ManifestValidationError` when the parsed document fails the schema.
+ */
+export class ManifestParseError extends Error {
+  constructor(
+    public readonly source: string,
+    public override readonly cause: unknown,
+  ) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(`.ninedeploy parse error: ${reason}`);
+    this.name = 'ManifestParseError';
+  }
+}
+
+export class ManifestValidationError extends Error {
+  constructor(
+    public readonly issues: ReadonlyArray<{ path: string; message: string }>,
+  ) {
+    const detail = issues.map((i) => `  - ${i.path || '<root>'}: ${i.message}`).join('\n');
+    super(`.ninedeploy validation failed:\n${detail}`);
+    this.name = 'ManifestValidationError';
+  }
+}
+
+export function parseManifestYaml(yamlText: string): NinedeployManifest {
+  let doc: unknown;
+  try {
+    doc = yaml.load(yamlText);
+  } catch (err) {
+    throw new ManifestParseError('<string>', err);
+  }
+  if (doc == null) {
+    throw new ManifestValidationError([{ path: '', message: 'manifest is empty' }]);
+  }
+  const result = ninedeployManifest.safeParse(doc);
+  if (!result.success) {
+    throw new ManifestValidationError(
+      result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * Format a manifest as YAML for round-tripping (download a manifest the
+ * server parsed, or write one to a fresh repo). Produces a header comment
+ * explaining the file and uses block style for nested objects.
+ */
+export function formatManifestYaml(manifest: NinedeployManifest): string {
+  // Hand-rolled YAML emission: the manifest is small and stable enough that
+  // depending on a second pass through `yaml.load` would be a waste. Block
+  // style throughout so the file is human-editable.
+  const lines: string[] = [
+    '# .ninedeploy — NineDeploy project manifest.',
+    '# Committed to the repo. Secrets NEVER go in this file — use the panel env vault.',
+    `# Generated by @ninedeploy/sdk on ${new Date().toISOString()}.`,
+    'version: "1"',
+  ];
+
+  if (manifest.runtime) {
+    lines.push('runtime:');
+    lines.push(`  type: ${manifest.runtime.type}`);
+    if (manifest.runtime.version) lines.push(`  version: "${manifest.runtime.version}"`);
+  }
+
+  if (manifest.build) {
+    lines.push(manifest.build.install || manifest.build.build || manifest.build.start || manifest.build.baseDir || manifest.build.dockerfile ? 'build:' : 'build: {}');
+    if (manifest.build.install) lines.push(`  install: ${quote(manifest.build.install)}`);
+    if (manifest.build.build) lines.push(`  build: ${quote(manifest.build.build)}`);
+    if (manifest.build.start) lines.push(`  start: ${quote(manifest.build.start)}`);
+    if (manifest.build.baseDir) lines.push(`  baseDir: ${quote(manifest.build.baseDir)}`);
+    if (manifest.build.dockerfile) lines.push(`  dockerfile: ${quote(manifest.build.dockerfile)}`);
+  }
+
+  if (manifest.run) {
+    lines.push(manifest.run.port != null || manifest.run.healthcheck || manifest.run.restart ? 'run:' : 'run: {}');
+    if (manifest.run.port != null) lines.push(`  port: ${manifest.run.port}`);
+    if (manifest.run.healthcheck) lines.push(`  healthcheck: ${quote(manifest.run.healthcheck)}`);
+    if (manifest.run.restart) lines.push(`  restart: ${quote(manifest.run.restart)}`);
+  }
+
+  if (manifest.static) {
+    lines.push('static:');
+    lines.push(`  spa: ${manifest.static.spa}`);
+    if (manifest.static.root) lines.push(`  root: ${quote(manifest.static.root)}`);
+  }
+
+  if (manifest.env) {
+    lines.push(manifest.env.required.length > 0 || manifest.env.aliases ? 'env:' : 'env: {}');
+    if (manifest.env.required.length > 0) {
+      lines.push('  required:');
+      for (const k of manifest.env.required) lines.push(`    - ${quote(k)}`);
+    }
+    if (manifest.env.aliases) {
+      lines.push(Object.keys(manifest.env.aliases).length > 0 ? '  aliases:' : '  aliases: {}');
+      for (const [from, to] of Object.entries(manifest.env.aliases)) {
+        lines.push(`    ${quote(from)}: ${quote(to)}`);
+      }
+    }
+  }
+
+  if (manifest.phases) {
+    lines.push(manifest.phases.setup || manifest.phases.build ? 'phases:' : 'phases: {}');
+    if (manifest.phases.setup) {
+      lines.push('  setup:');
+      lines.push(manifest.phases.setup.pkgs.length > 0 ? '    pkgs:' : '    pkgs: []');
+      for (const p of manifest.phases.setup.pkgs) lines.push(`      - ${quote(p)}`);
+    }
+    if (manifest.phases.build) {
+      lines.push('  build:');
+      lines.push(manifest.phases.build.cmds.length > 0 ? '    cmds:' : '    cmds: []');
+      for (const c of manifest.phases.build.cmds) lines.push(`      - ${quote(c)}`);
+    }
+  }
+
+  if (manifest.resources) {
+    lines.push(manifest.resources.cpuShares != null || manifest.resources.cpuLimitMilli != null || manifest.resources.memMb != null || manifest.resources.replicas != null ? 'resources:' : 'resources: {}');
+    if (manifest.resources.cpuShares != null) lines.push(`  cpuShares: ${manifest.resources.cpuShares}`);
+    if (manifest.resources.cpuLimitMilli != null) lines.push(`  cpuLimitMilli: ${manifest.resources.cpuLimitMilli}`);
+    if (manifest.resources.memMb != null) lines.push(`  memMb: ${manifest.resources.memMb}`);
+    if (manifest.resources.replicas != null) lines.push(`  replicas: ${manifest.resources.replicas}`);
+  }
+
+  if (manifest.hooks) {
+    lines.push(manifest.hooks.preBuild || manifest.hooks.postBuild || manifest.hooks.preStop ? 'hooks:' : 'hooks: {}');
+    if (manifest.hooks.preBuild) lines.push(`  preBuild: ${quote(manifest.hooks.preBuild)}`);
+    if (manifest.hooks.postBuild) lines.push(`  postBuild: ${quote(manifest.hooks.postBuild)}`);
+    if (manifest.hooks.preStop) lines.push(`  preStop: ${quote(manifest.hooks.preStop)}`);
+  }
+
+  if (manifest.watch) {
+    lines.push('watch:');
+    lines.push(manifest.watch.paths.length > 0 ? '  paths:' : '  paths: []');
+    for (const p of manifest.watch.paths) lines.push(`    - ${quote(p)}`);
+  }
+
+  if (manifest.routes) {
+    lines.push(manifest.routes.length > 0 ? 'routes:' : 'routes: []');
+    for (const r of manifest.routes) {
+      lines.push(`  - host: ${quote(r.host)}`);
+      lines.push(`    path: ${quote(r.path)}`);
+      lines.push(`    ssl: ${r.ssl}`);
+      if (r.redirectWww !== undefined) lines.push(`    redirectWww: ${r.redirectWww}`);
+      if (r.headers) {
+        lines.push(Object.keys(r.headers).length > 0 ? '    headers:' : '    headers: {}');
+        for (const [k, v] of Object.entries(r.headers)) lines.push(`      ${quote(k)}: ${quote(v)}`);
+      }
+      if (r.ipAllowlist) {
+        lines.push(r.ipAllowlist.length > 0 ? '    ipAllowlist:' : '    ipAllowlist: []');
+        for (const cidr of r.ipAllowlist) lines.push(`      - ${quote(cidr)}`);
+      }
+      if (r.rateLimit) {
+        lines.push('    rateLimit:');
+        lines.push(`      average: ${r.rateLimit.average}`);
+        lines.push(`      burst: ${r.rateLimit.burst}`);
+      }
+    }
+  }
+
+  if (manifest.previews) {
+    lines.push('previews:');
+    lines.push(`  enabled: ${manifest.previews.enabled}`);
+    if (manifest.previews.pattern) lines.push(`  pattern: ${quote(manifest.previews.pattern)}`);
+    lines.push(`  maxActive: ${manifest.previews.maxActive}`);
+    lines.push(`  autoDestroyOnClose: ${manifest.previews.autoDestroyOnClose}`);
+  }
+
+  if (manifest.volume) {
+    lines.push(manifest.volume.mount != null || manifest.volume.backups ? 'volume:' : 'volume: {}');
+    if (manifest.volume.mount != null) lines.push(`  mount: ${quote(manifest.volume.mount)}`);
+    if (manifest.volume.backups) {
+      lines.push('  backups:');
+      lines.push(`    schedule: ${quote(manifest.volume.backups.schedule)}`);
+      lines.push(`    retention: ${manifest.volume.backups.retention}`);
+    }
+  }
+
+  if (manifest.database) {
+    lines.push('database:');
+    lines.push(`  ref: ${quote(manifest.database.ref)}`);
+    lines.push(`  env: ${quote(manifest.database.env)}`);
+  }
+
+  if (manifest.network) {
+    lines.push(manifest.network.publishPort != null || manifest.network.aliases.length > 0 ? 'network:' : 'network: {}');
+    if (manifest.network.publishPort != null) lines.push(`  publishPort: ${manifest.network.publishPort}`);
+    if (manifest.network.aliases.length > 0) {
+      lines.push('  aliases:');
+      for (const a of manifest.network.aliases) lines.push(`    - ${quote(a)}`);
+    }
+  }
+
+  if (manifest.notifications) {
+    lines.push(manifest.notifications.onDeploy.length > 0 || manifest.notifications.onFailure.length > 0 || manifest.notifications.onAlert.length > 0 ? 'notifications:' : 'notifications: {}');
+    if (manifest.notifications.onDeploy.length > 0) {
+      lines.push('  onDeploy:');
+      for (const c of manifest.notifications.onDeploy) lines.push(`    - ${quote(c)}`);
+    }
+    if (manifest.notifications.onFailure.length > 0) {
+      lines.push('  onFailure:');
+      for (const c of manifest.notifications.onFailure) lines.push(`    - ${quote(c)}`);
+    }
+    if (manifest.notifications.onAlert.length > 0) {
+      lines.push('  onAlert:');
+      for (const c of manifest.notifications.onAlert) lines.push(`    - ${quote(c)}`);
+    }
+  }
+
+  if (manifest.alerts) {
+    lines.push(manifest.alerts.length > 0 ? 'alerts:' : 'alerts: []');
+    for (const a of manifest.alerts) {
+      lines.push(`  - when: ${a.when}`);
+      lines.push(`    channel: ${quote(a.channel)}`);
+      if (a.thresholdPct != null) lines.push(`    thresholdPct: ${a.thresholdPct}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function quote(value: string): string {
+  // Plain when unambiguously safe; otherwise a double-quoted YAML scalar via
+  // JSON escaping. JSON's escapes (\" \\ \n \t \uXXXX) are a subset of YAML's
+  // double-quote escapes, so embedded newlines survive a round-trip instead
+  // of folding into spaces, and ` #` sequences stay inside the scalar instead
+  // of truncating it as a comment.
+  // The charset check alone is NOT "unambiguously safe": YAML resolves
+  // charset-safe scalars like `true`, `8080`, `007` or `2024-01-01` to
+  // booleans/numbers/timestamps, which would turn a string value (e.g. a
+  // route header) into a different type on the next parse (r023). So a
+  // candidate plain scalar is emitted bare only when js-yaml loads it back
+  // as a string.
+  if (/^[A-Za-z0-9._/-]+$/.test(value)) {
+    const loaded: unknown = yaml.load(value);
+    if (typeof loaded === 'string') return value;
+  }
+  return JSON.stringify(value);
+}
+
+// ── Project-type detection for `init` ────────────────────────────────────
+
+export type ProjectKind = 'node-npm' | 'node-pnpm' | 'python' | 'go' | 'static' | 'unknown';
+
+const PROJECT_MARKERS: ReadonlyArray<{ kind: ProjectKind; files: ReadonlyArray<string> }> = [
+  { kind: 'node-pnpm', files: ['pnpm-lock.yaml', 'pnpm-workspace.yaml'] },
+  { kind: 'python', files: ['pyproject.toml', 'requirements.txt', 'Pipfile'] },
+  { kind: 'go', files: ['go.mod'] },
+  { kind: 'static', files: ['vite.config.ts', 'vite.config.js', 'index.html'] },
+  { kind: 'node-npm', files: ['package.json'] },
+];
+
+/**
+ * Pick a starter-template kind from a list of files present in the repo
+ * root. The first match wins. Order in `PROJECT_MARKERS` is the precedence:
+ * pnpm is more specific than the generic `package.json`; `static` is for
+ * Vite/static frontends without a build server.
+ */
+export function detectProjectKind(files: ReadonlyArray<string>): ProjectKind {
+  for (const marker of PROJECT_MARKERS) {
+    if (marker.files.some((f) => files.includes(f))) return marker.kind;
+  }
+  return 'unknown';
+}
+
+/**
+ * Read a recommended version out of `RUNTIME_VERSION_CATALOG`. Throws rather
+ * than falling back to an unpinned runtime: a starter that silently stopped
+ * pinning a version would be a far subtler bug than a loud one.
+ */
+function pin(type: 'node' | 'python' | 'go'): string {
+  const version = recommendedRuntimeVersion(type);
+  /* c8 ignore next -- unreachable: the catalog always carries these three. */
+  if (!version) throw new Error(`runtime catalog has no recommended version for "${type}"`);
+  return version;
+}
+
+/**
+ * Produce a starter `.ninedeploy` for a given project kind. The result is
+ * opinionated: it pins the recommended runtime version, uses the manifest to
+ * declare a domain placeholder, and sets sensible defaults. The operator is
+ * expected to edit the file before committing.
+ *
+ * Versions are never written literally here — they come from the runtime
+ * catalog in `@ninedeploy/schemas`, the one place they are maintained, so the
+ * CLI and the web Manifest Creator can never disagree about what "current" means.
+ */
+export function starterManifest(kind: ProjectKind): NinedeployManifest {
+  switch (kind) {
+    case 'node-npm':
+      return {
+        version: '1',
+        runtime: { type: 'node', version: pin('node') },
+        build: { install: 'npm ci', build: 'npm run build', start: 'npm start' },
+        run: { port: 3000, restart: 'unless-stopped' },
+        routes: [{ host: 'app.example.com', path: '/', ssl: true }],
+      };
+    case 'node-pnpm':
+      return {
+        version: '1',
+        runtime: { type: 'node', version: pin('node') },
+        build: { install: 'pnpm install --frozen-lockfile', build: 'pnpm build', start: 'pnpm start' },
+        run: { port: 3000, restart: 'unless-stopped' },
+      };
+    case 'python':
+      return {
+        version: '1',
+        runtime: { type: 'python', version: pin('python') },
+        build: { install: 'pip install -r requirements.txt', start: 'python main.py' },
+        run: { port: 8000, restart: 'unless-stopped' },
+      };
+    case 'go':
+      return {
+        version: '1',
+        runtime: { type: 'go', version: pin('go') },
+        build: { build: 'go build -o app .', start: './app' },
+        run: { port: 8080, restart: 'unless-stopped' },
+      };
+    case 'static':
+      return {
+        version: '1',
+        static: { spa: true, root: 'dist' },
+        build: { install: 'npm ci', build: 'npm run build' },
+        run: { port: 3000, restart: 'unless-stopped' },
+      };
+    case 'unknown':
+      return {
+        version: '1',
+        runtime: { type: 'auto' },
+        run: { port: 3000, restart: 'unless-stopped' },
+      };
+  }
+}
+
+// ── Template-bundle manifest generation (G-04) ──────────────────────────
+
+/**
+ * Minimal subset of a template-registry entry that the manifest generator
+ * needs. The full server-side `Template` type carries fields that the
+ * manifest does not need (category, emoji, website, …), so the SDK pins
+ * the smaller shape and the server adapts its full entry down to it.
+ */
+export interface TemplateRegistryEntry {
+  id: string;
+  name: string;
+  image: string;
+  port?: number;
+  volumeMount?: string;
+  env?: Array<{ key: string; value: string; secret: boolean }>;
+}
+
+/**
+ * Pure mapping from a template-registry entry to a starter `.ninedeploy`
+ * manifest. Used by the server-side `manifest-generator` plugin (which
+ * listens for `template.bundle.observed`) and by the CLI's
+ * `ninedeploy template-bundles init` command.
+ *
+ * Contract:
+ *   - Always sets `version: "1"` and `runtime.type: "auto"`.
+ *   - Copies `port` from the registry entry into `run.port`.
+ *   - Default `run.healthcheck` is `/` and `run.restart` is `unless-stopped`
+ *     (matches the host-privilege boundary — restart-on-failure is operator
+ *     territory, so the panel decides, not the bundle).
+ *   - Copies `volumeMount` into `volume.mount` when present.
+ *   - Pulls every `env.key` from the registry into `env.required`. We never
+ *     copy values, only the names — the manifest is committed to the repo,
+ *     and the loader's secret scan refuses credential-shaped values anyway.
+ *   - Emits a single starter route (`host: provided`, `path: '/'`, `ssl: true`)
+ *     for the operator to edit.
+ */
+export function buildManifestFromTemplate(
+  entry: TemplateRegistryEntry,
+  defaultHost: string = '',
+): NinedeployManifest {
+  // Start with the bare minimum and layer optional fields only when the
+  // registry entry has something to contribute. Leaving `env` undefined
+  // (rather than `env: { required: [] }`) keeps the rendered YAML clean
+  // — `env:` with no children would otherwise parse back as `env: null`,
+  // which the schema rejects.
+  const manifest: NinedeployManifest = {
+    version: '1',
+    runtime: { type: 'auto' },
+    run: {
+      healthcheck: '/',
+      restart: 'unless-stopped',
+    },
+    routes: [{ host: defaultHost, path: '/', ssl: true }],
+  };
+  if (typeof entry.port === 'number') {
+    manifest.run = { ...manifest.run, port: entry.port };
+  }
+  if (entry.volumeMount) {
+    manifest.volume = { mount: entry.volumeMount };
+  }
+  if (entry.env && entry.env.length > 0) {
+    manifest.env = { required: entry.env.map((e) => e.key) };
+  }
+  return manifest;
+}