@dockerforge/core 0.1.0

package/src/_engine/shared/constants.js

@@ -0,0 +1,98 @@
+// shared/constants.js
+// Shared between frontend and backend
+
+const STACKS = {
+  NODE: 'node',
+  PYTHON: 'python',
+  DOTNET: 'dotnet',
+};
+
+const DETECTION_FILES = {
+  [STACKS.NODE]: ['package.json'],
+  [STACKS.PYTHON]: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
+  [STACKS.DOTNET]: ['.csproj'], // matched by extension
+};
+
+const BASE_IMAGES = {
+  [STACKS.NODE]: (version) => `node:${version}-alpine3.21`,
+  [STACKS.PYTHON]: (version) => `python:${version}-slim`,
+  [STACKS.DOTNET]: {
+    runtime: (version) => `mcr.microsoft.com/dotnet/aspnet:${version}`,
+    sdk: (version) => `mcr.microsoft.com/dotnet/sdk:${version}`,
+  },
+};
+
+const DEFAULT_VERSIONS = {
+  [STACKS.NODE]: '20',
+  [STACKS.PYTHON]: '3.12',
+  [STACKS.DOTNET]: '8.0',
+};
+
+const DEFAULT_PORTS = {
+  [STACKS.NODE]: 3000,
+  [STACKS.PYTHON]: 8000,
+  [STACKS.DOTNET]: 8080,
+};
+
+const IGNORED_DIRS = [
+  '.git',
+  'node_modules',
+  '__pycache__',
+  '.pytest_cache',
+  'bin',
+  'obj',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  'coverage',
+  '.venv',
+  'venv',
+  'env',
+  // test infra
+  '__tests__',
+  '__mocks__',
+  'test',
+  'tests',
+  'fixtures',
+  'spec',
+  'specs',
+  // sample / docs — not deployable services
+  'examples',
+  'example',
+  'samples',
+  'sample',
+  'demos',
+  'demo',
+  'docs',
+  'doc',
+  'dev-docs',
+  'documentation',
+];
+
+// Root-level config files that affect compiled output and must be COPYed into build stages.
+// Dev-only tools (eslint, prettier, stylelint, editorconfig) are deliberately excluded —
+// they don't affect npm run build output and are typically in .dockerignore.
+const ROOT_CONFIG_FILES = [
+  // TypeScript compilation
+  'tsconfig.json', 'tsconfig.base.json', 'tsconfig.build.json', 'tsconfig.app.json',
+  // Babel
+  'babel.config.js', 'babel.config.cjs', 'babel.config.mjs', 'babel.config.json',
+  '.babelrc', '.babelrc.js', '.babelrc.json',
+  // PostCSS (affects CSS output)
+  'postcss.config.js', 'postcss.config.cjs', 'postcss.config.mjs',
+  // ESLint — react-scripts/Next.js run ESLint during `npm run build`
+  '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.mjs',
+  '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+];
+
+module.exports = {
+  STACKS,
+  DETECTION_FILES,
+  BASE_IMAGES,
+  DEFAULT_VERSIONS,
+  DEFAULT_PORTS,
+  IGNORED_DIRS,
+  ROOT_CONFIG_FILES,
+};

package/src/errors.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// Typed error model for @dockerforge/core (see docs/contracts/core-contract.md, Section 4).
+// Core throws these, never a bare Error, so callers can branch on `.code` reliably.
+
+class DockerForgeError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+  }
+}
+
+class PathNotFoundError extends DockerForgeError {
+  constructor(message) { super(message, 'PATH_NOT_FOUND'); }
+}
+
+class NotADirectoryError extends DockerForgeError {
+  constructor(message) { super(message, 'NOT_A_DIRECTORY'); }
+}
+
+class UnsupportedStackError extends DockerForgeError {
+  constructor(message) { super(message, 'UNSUPPORTED_STACK'); }
+}
+
+class IngestError extends DockerForgeError {
+  constructor(message) { super(message, 'INGEST_ERROR'); }
+}
+
+module.exports = {
+  DockerForgeError,
+  PathNotFoundError,
+  NotADirectoryError,
+  UnsupportedStackError,
+  IngestError,
+};

package/src/index.js

@@ -0,0 +1,70 @@
+'use strict';
+
+// @dockerforge/core - thin facade (Chunk 0.3).
+//
+// This re-exports the CURRENT engine in backend/src/modules/* UNCHANGED. We do not move
+// internals yet (that happens gradually, file-by-file, behind the existing ~600 tests).
+// What this file fixes is the PUBLIC SURFACE: it is exactly the contract in
+// docs/contracts/core-contract.md. The CLI and the Cloud API code against this, not against
+// backend/src/modules paths.
+//
+// No-network guarantee: this module performs zero outbound network calls. It only reads the
+// local filesystem under the resolved project path. Remote ingestion (git URL / zip URL) is
+// intentionally NOT exposed here - that adapter lives on the proprietary cloud side.
+
+const path = require('path');
+const fs = require('fs-extra');
+
+// Engine resolution: a published tarball vendors the engine under ./_engine (see
+// scripts/vendor-engine.js, run at prepack). In the monorepo (dev/test) that dir does not
+// exist, so we fall back to the canonical backend/ source. Same code either way.
+const _vendoredEngine = require('path').join(__dirname, '_engine', 'backend', 'src', 'modules', 'engine.js');
+const engine = require('fs').existsSync(_vendoredEngine)
+  ? require(_vendoredEngine)
+  : require('../../../backend/src/modules/engine');
+const errors = require('./errors');
+const { lint } = require('./lint');
+
+/**
+ * Validate a local directory and return its resolved absolute path.
+ * Throws typed errors (PathNotFoundError / NotADirectoryError) per the contract.
+ * @param {string} targetPath
+ * @returns {Promise<string>}
+ */
+async function ingestLocal(targetPath) {
+  const resolved = path.resolve(targetPath);
+  let stat;
+  try {
+    stat = await fs.stat(resolved);
+  } catch {
+    throw new errors.PathNotFoundError(`Path not found: ${resolved}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new errors.NotADirectoryError(`Not a directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+/**
+ * Run the offline engine pipeline. Only the documented OFFLINE input fields are accepted;
+ * remote-ingest fields (gitUrl/zipPath/fileTree/workDir/pat) are deliberately not forwarded.
+ * @param {{projectPath: string, hints?: object, optimise?: boolean, security?: boolean, validation?: object|null}} input
+ * @returns {Promise<object>} EngineResult (see contract Section 2.2)
+ */
+async function runDockerfileEngine(input = {}) {
+  const { projectPath, hints, optimise, security, validation } = input;
+  if (!projectPath) {
+    throw new errors.IngestError(
+      'projectPath is required: @dockerforge/core is offline. Remote ingestion (git URL/zip) lives in the cloud adapter, not core.'
+    );
+  }
+  return engine.runDockerfileEngine({ projectPath, hints, optimise, security, validation });
+}
+
+module.exports = {
+  ingestLocal,
+  runDockerfileEngine,
+  lint,
+  // typed errors, re-exported so consumers import them from the package root
+  ...errors,
+};

package/src/lint/index.js

@@ -0,0 +1,92 @@
+'use strict';
+
+// @dockerforge/core lint engine (Chunk 1.2). Offline, pure-ish (reads local files only).
+// Returns a LintResult per the contract (Section 2.3). Serialisation (SARIF/JSON/human) is
+// the CLI's job, not core's.
+
+const path = require('path');
+const fs = require('fs/promises');
+
+const { parseDockerfile, toStages, collectAliases } = require('./parse');
+const { RULES } = require('./rules');
+const errors = require('../errors');
+
+const SEVERITY_ORDER = ['info', 'low', 'medium', 'high', 'critical'];
+
+async function readIfExists(p) {
+  try { return await fs.readFile(p, 'utf8'); } catch { return null; }
+}
+
+// Resolve the lint target into { dockerfileText, fsContext }.
+// target: string (path to a Dockerfile or a project dir) OR { dockerfile: string }.
+async function resolveTarget(target) {
+  if (target && typeof target === 'object' && typeof target.dockerfile === 'string') {
+    return { dockerfileText: target.dockerfile, fsContext: { hasFsContext: false, dockerignore: null } };
+  }
+  if (typeof target !== 'string') {
+    throw new errors.IngestError('lint target must be a path string or { dockerfile } object');
+  }
+
+  const resolved = path.resolve(target);
+  let stat;
+  try { stat = await fs.stat(resolved); }
+  catch { throw new errors.PathNotFoundError(`Path not found: ${resolved}`); }
+
+  let dockerfilePath;
+  let dir;
+  if (stat.isDirectory()) {
+    dir = resolved;
+    dockerfilePath = path.join(resolved, 'Dockerfile');
+  } else {
+    dir = path.dirname(resolved);
+    dockerfilePath = resolved;
+  }
+
+  const dockerfileText = await readIfExists(dockerfilePath);
+  if (dockerfileText === null) {
+    throw new errors.PathNotFoundError(`Dockerfile not found: ${dockerfilePath}`);
+  }
+
+  const diContent = await readIfExists(path.join(dir, '.dockerignore'));
+  return {
+    dockerfileText,
+    fsContext: {
+      hasFsContext: true,
+      dockerignore: diContent === null ? { exists: false, content: '' } : { exists: true, content: diContent },
+    },
+  };
+}
+
+/**
+ * Lint a Dockerfile.
+ * @param {string|{dockerfile:string}} target
+ * @param {{failOn?:string, rules?:string[]}} [options]
+ * @returns {Promise<{findings:Array, summary:{counts:object, worst:string|null}}>}
+ */
+async function lint(target, options = {}) {
+  const { dockerfileText, fsContext } = await resolveTarget(target);
+
+  const instructions = parseDockerfile(dockerfileText);
+  const stages = toStages(instructions);
+  const aliases = collectAliases(stages);
+  const ctx = { instructions, stages, aliases, ...fsContext };
+
+  const enabled = options.rules && options.rules.length ? new Set(options.rules) : null;
+
+  let findings = [];
+  for (const rule of RULES) {
+    if (enabled && !enabled.has(rule.id)) continue;
+    findings = findings.concat(rule.check(ctx));
+  }
+
+  findings.sort((a, b) => (a.line || 0) - (b.line || 0) || a.ruleId.localeCompare(b.ruleId));
+
+  const counts = { info: 0, low: 0, medium: 0, high: 0, critical: 0 };
+  for (const f of findings) counts[f.severity]++;
+  let worst = null;
+  for (const s of SEVERITY_ORDER) if (counts[s] > 0) worst = s;
+
+  return { findings, summary: { counts, worst } };
+}
+
+module.exports = { lint, SEVERITY_ORDER };

package/src/lint/parse.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// Minimal, deterministic Dockerfile parser for the lint engine (Chunk 1.2).
+// Not a full Dockerfile grammar - just enough to evaluate the 6 cheap rules reliably.
+// Handles comments, blank lines, and backslash line-continuations, tracking line numbers.
+
+function parseDockerfile(text) {
+  const rawLines = String(text).split(/\r?\n/);
+  const instructions = [];
+  let i = 0;
+
+  while (i < rawLines.length) {
+    const startLine = i + 1;
+    const trimmed = rawLines[i].trim();
+
+    if (trimmed === '' || trimmed.startsWith('#')) { i++; continue; }
+
+    // Join continuation lines (trailing backslash).
+    let content = rawLines[i];
+    while (/\\\s*$/.test(content) && i + 1 < rawLines.length) {
+      content = content.replace(/\\\s*$/, ' ');
+      i++;
+      content += rawLines[i];
+    }
+
+    const m = content.trim().match(/^(\w+)\s*([\s\S]*)$/);
+    if (m) {
+      instructions.push({
+        instruction: m[1].toUpperCase(),
+        args: (m[2] || '').trim(),
+        line: startLine,
+      });
+    }
+    i++;
+  }
+
+  return instructions;
+}
+
+// Split a flat instruction list into stages (one per FROM). Instructions before the
+// first FROM (rare; e.g. top-level ARG) are ignored for stage-scoped rules.
+function toStages(instructions) {
+  const stages = [];
+  let current = null;
+  for (const ins of instructions) {
+    if (ins.instruction === 'FROM') {
+      current = { from: ins, instructions: [] };
+      stages.push(current);
+    } else if (current) {
+      current.instructions.push(ins);
+    }
+  }
+  return stages;
+}
+
+// Collect lowercased stage aliases (FROM x AS <alias>) so base-image rules can skip
+// "FROM <previous-stage>" references.
+function collectAliases(stages) {
+  const aliases = new Set();
+  for (const stage of stages) {
+    const m = stage.from.args.match(/\s+AS\s+(\S+)\s*$/i);
+    if (m) aliases.add(m[1].toLowerCase());
+  }
+  return aliases;
+}
+
+// Parse ENV pairs: supports "ENV K=V K2=V2" (quoted values) and legacy "ENV K V...".
+function parseEnvPairs(args) {
+  const t = args.trim();
+  if (t.includes('=')) {
+    const pairs = [];
+    const re = /([A-Za-z_][\w.-]*)=("([^"]*)"|'([^']*)'|\S+)/g;
+    let m;
+    while ((m = re.exec(t))) {
+      const value = m[3] !== undefined ? m[3] : (m[4] !== undefined ? m[4] : m[2]);
+      pairs.push({ key: m[1], value });
+    }
+    return pairs;
+  }
+  const sp = t.split(/\s+/);
+  const key = sp.shift();
+  return key ? [{ key, value: sp.join(' ') }] : [];
+}
+
+// Parse "ARG KEY[=DEFAULT]".
+function parseArg(args) {
+  const t = args.trim();
+  const eq = t.indexOf('=');
+  if (eq === -1) return { key: t.split(/\s+/)[0] || '', value: null };
+  return {
+    key: t.slice(0, eq).trim(),
+    value: t.slice(eq + 1).trim().replace(/^["']|["']$/g, ''),
+  };
+}
+
+// Strip COPY/ADD flags (--from=, --chown=, --chmod=, --link) and return the remaining tokens.
+function instructionTokens(args) {
+  return args
+    .replace(/--[\w-]+(=\S+)?/g, '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+module.exports = {
+  parseDockerfile,
+  toStages,
+  collectAliases,
+  parseEnvPairs,
+  parseArg,
+  instructionTokens,
+};

package/src/lint/rules.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// The first-wave lint rules (Chunk 1.2): cheap, deterministic, low false-positive.
+// Each rule: { id, title, check(ctx) -> Finding[] }. A Finding is
+// { ruleId, severity, message, fixHint, line|null }.
+// Second-wave rules (EOL base, multi-stage detection, apt cache, ADD-vs-COPY) come later.
+
+const { parseEnvPairs, parseArg, instructionTokens } = require('./parse');
+
+const SECRET_KEY = /(passwd|password|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credential|auth_?key)/i;
+const ENV_EXCLUDE = ['.env', '.env*', '*.env', '.env.*', '**/.env'];
+
+function finding(ruleId, severity, message, fixHint, line) {
+  return { ruleId, severity, message, fixHint, line: line ?? null };
+}
+
+// DF001 - base image not pinned (:latest or no tag).
+const unpinnedBase = {
+  id: 'DF001',
+  title: 'Base image is not pinned',
+  check(ctx) {
+    const out = [];
+    for (const stage of ctx.stages) {
+      let ref = stage.from.args.replace(/\s+AS\s+\S+\s*$/i, '').replace(/--platform=\S+\s*/i, '').trim();
+      const base = ref.toLowerCase();
+      if (!ref || base === 'scratch') continue;
+      if (ctx.aliases.has(base)) continue;        // FROM <previous stage>
+      if (ref.includes('@sha256:')) continue;      // digest-pinned
+      const lastSeg = ref.split('/').pop();        // avoids registry:port false-positive
+      const tag = lastSeg.includes(':') ? lastSeg.split(':').pop() : null;
+      if (!tag) {
+        out.push(finding('DF001', 'high', `Base image "${ref}" has no tag (implies :latest).`,
+          'Pin to an explicit version, ideally a digest (e.g. node:20-alpine@sha256:...).', stage.from.line));
+      } else if (tag === 'latest') {
+        out.push(finding('DF001', 'high', `Base image "${ref}" uses the :latest tag.`,
+          'Pin to an explicit version, ideally a digest, so builds are reproducible.', stage.from.line));
+      }
+    }
+    return out;
+  },
+};
+
+// DF002 - final stage runs as root (no non-root USER).
+const rootUser = {
+  id: 'DF002',
+  title: 'Container runs as root',
+  check(ctx) {
+    const stage = ctx.stages[ctx.stages.length - 1];
+    if (!stage) return [];
+    const users = stage.instructions.filter((i) => i.instruction === 'USER');
+    if (users.length === 0) {
+      return [finding('DF002', 'high', 'No USER set in the final stage; the container runs as root.',
+        'Create and switch to a non-root user before the start command (USER app).', stage.from.line)];
+    }
+    const last = users[users.length - 1];
+    const u = (last.args.trim().split(/\s+/)[0] || '').toLowerCase();
+    if (u === 'root' || u === '0') {
+      return [finding('DF002', 'high', 'Final USER is root.',
+        'Switch to a non-root user before the start command.', last.line)];
+    }
+    return [];
+  },
+};
+
+// DF003 - COPY . . (leaks the whole build context, including secrets).
+const copyDotDot = {
+  id: 'DF003',
+  title: 'COPY . . copies the entire context',
+  check(ctx) {
+    const out = [];
+    for (const ins of ctx.instructions) {
+      if (ins.instruction !== 'COPY') continue;
+      const toks = instructionTokens(ins.args);
+      if (toks.length === 2 && toks[0] === '.' && (toks[1] === '.' || toks[1] === './')) {
+        out.push(finding('DF003', 'high', 'COPY . . copies the entire build context (risks leaking .env, secrets, .git).',
+          'Copy only what you need (manifests, lockfiles, src/) and rely on a .dockerignore.', ins.line));
+      }
+    }
+    return out;
+  },
+};
+
+// DF004 - .dockerignore missing or does not exclude .env (needs filesystem context).
+const dockerignoreEnv = {
+  id: 'DF004',
+  title: '.dockerignore missing or does not exclude .env',
+  check(ctx) {
+    if (!ctx.hasFsContext) return []; // raw-string lint: no sibling file to check
+    if (!ctx.dockerignore || !ctx.dockerignore.exists) {
+      return [finding('DF004', 'medium', 'No .dockerignore found next to the Dockerfile.',
+        'Add a .dockerignore that excludes .env, node_modules, .git, and build output.', null)];
+    }
+    const lines = String(ctx.dockerignore.content).split(/\r?\n/).map((l) => l.trim());
+    const excludesEnv = lines.some((l) => ENV_EXCLUDE.includes(l));
+    if (!excludesEnv) {
+      return [finding('DF004', 'medium', '.dockerignore does not exclude .env.',
+        'Add a ".env" line (and ".env.*") so secrets never enter the build context.', null)];
+    }
+    return [];
+  },
+};
+
+// DF005 - secret-like value hardcoded in ENV/ARG.
+const hardcodedSecret = {
+  id: 'DF005',
+  title: 'Secret-like value hardcoded in ENV/ARG',
+  check(ctx) {
+    const out = [];
+    const isVarRef = (v) => /^\$\{?\w+\}?$/.test(v);
+    for (const ins of ctx.instructions) {
+      if (ins.instruction === 'ENV') {
+        for (const { key, value } of parseEnvPairs(ins.args)) {
+          if (SECRET_KEY.test(key) && value && value.trim() !== '' && !isVarRef(value.trim())) {
+            out.push(finding('DF005', 'critical', `ENV "${key}" hardcodes a secret-like value.`,
+              'Do not bake secrets into the image. Pass at runtime (env/secret), not in the Dockerfile.', ins.line));
+          }
+        }
+      } else if (ins.instruction === 'ARG') {
+        const { key, value } = parseArg(ins.args);
+        if (SECRET_KEY.test(key) && value && value.trim() !== '' && !isVarRef(value.trim())) {
+          out.push(finding('DF005', 'critical', `ARG "${key}" has a secret-like default value baked into the image history.`,
+            'Remove the default; supply secrets at build/run time via a secret mount, not ARG.', ins.line));
+        }
+      }
+    }
+    return out;
+  },
+};
+
+// DF006 - final stage has no WORKDIR.
+const missingWorkdir = {
+  id: 'DF006',
+  title: 'No WORKDIR set in the final stage',
+  check(ctx) {
+    const stage = ctx.stages[ctx.stages.length - 1];
+    if (!stage) return [];
+    const hasWorkdir = stage.instructions.some((i) => i.instruction === 'WORKDIR');
+    if (!hasWorkdir) {
+      return [finding('DF006', 'low', 'No WORKDIR set in the final stage; paths default to /.',
+        'Set an explicit WORKDIR (e.g. WORKDIR /app) before COPY/RUN/CMD.', stage.from.line)];
+    }
+    return [];
+  },
+};
+
+const RULES = [unpinnedBase, rootUser, copyDotDot, dockerignoreEnv, hardcodedSecret, missingWorkdir];
+
+module.exports = { RULES };