@olwiba/dx 0.0.24 → 0.0.28

package/dist/cli.js

@@ -2353,12 +2353,147 @@ var init_generate_assets = __esm({
   }
 });
 
+// src/env-check.ts
+var env_check_exports = {};
+__export(env_check_exports, {
+  checkEnv: () => checkEnv,
+  formatEnvReport: () => formatEnvReport,
+  parseEnv: () => parseEnv
+});
+function parseEnv(source) {
+  const keys = /* @__PURE__ */ new Map();
+  const duplicates = [];
+  const malformed = [];
+  source.split(/\r?\n/).forEach((raw, index) => {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) return;
+    const withoutExport = line.replace(/^export\s+/, "");
+    const eq = withoutExport.indexOf("=");
+    if (eq <= 0) {
+      malformed.push({ line: index + 1, text: withoutExport.slice(0, 24) });
+      return;
+    }
+    const key = withoutExport.slice(0, eq).trim();
+    const value = withoutExport.slice(eq + 1).trim();
+    if (keys.has(key)) duplicates.push(key);
+    keys.set(key, value !== "" && value !== '""' && value !== "''");
+  });
+  return { keys, duplicates, malformed };
+}
+function findRenameCandidate(unknownKey, knownKeys) {
+  const normalise = (key) => key.replace(/[^A-Z0-9]/gi, "").toUpperCase();
+  const target = normalise(unknownKey);
+  return knownKeys.find((known) => {
+    const candidate = normalise(known);
+    if (candidate === target) return true;
+    return candidate.length >= 6 && (target.endsWith(candidate) || target.startsWith(candidate));
+  });
+}
+function checkEnv({
+  example,
+  actual,
+  /** Keys allowed to be absent, e.g. optional credentials. */
+  optional = []
+}) {
+  const exampleEnv = parseEnv(example);
+  const actualEnv = parseEnv(actual);
+  const optionalSet = new Set(optional);
+  const exampleKeys = [...exampleEnv.keys.keys()];
+  const findings = [];
+  let okCount = 0;
+  for (const key of exampleKeys) {
+    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;
+    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;
+    if (!actualEnv.keys.has(key)) {
+      if (!isOptional) findings.push({ kind: "missing", key });
+      continue;
+    }
+    const hasValue = actualEnv.keys.get(key) === true;
+    if (!hasValue && !isOptional) {
+      findings.push({ kind: "empty", key });
+      continue;
+    }
+    okCount += 1;
+  }
+  for (const key of actualEnv.keys.keys()) {
+    if (exampleEnv.keys.has(key)) continue;
+    const looksLike = findRenameCandidate(key, exampleKeys);
+    findings.push(looksLike ? { kind: "renamed", key, looksLike } : { kind: "unknown", key });
+  }
+  for (const key of actualEnv.duplicates) findings.push({ kind: "duplicate", key });
+  for (const line of actualEnv.malformed) findings.push({ kind: "malformed", ...line });
+  return {
+    findings,
+    okCount,
+    exampleCount: exampleEnv.keys.size,
+    actualCount: actualEnv.keys.size
+  };
+}
+function formatEnvReport(result) {
+  const lines = [];
+  lines.push(
+    `  ${result.actualCount} keys checked against ${result.exampleCount} in the example, ${result.okCount} correct`
+  );
+  if (result.findings.length === 0) {
+    lines.push("\nPASS \u2014 environment matches the example.");
+    return lines.join("\n");
+  }
+  for (const kind of ORDER) {
+    const group = result.findings.filter((finding) => finding.kind === kind);
+    if (group.length === 0) continue;
+    lines.push(`
+${LABELS[kind]}:`);
+    for (const finding of group) {
+      if (finding.kind === "renamed") {
+        lines.push(`  \u2717 ${finding.key}  \u2192  did you mean ${finding.looksLike}?`);
+      } else if (finding.kind === "malformed") {
+        lines.push(`  \u2717 line ${finding.line}: ${finding.text}\u2026`);
+      } else {
+        lines.push(`  \u2717 ${finding.key}`);
+      }
+    }
+  }
+  const renamed = result.findings.filter((finding) => finding.kind === "renamed").length;
+  if (renamed > 0) {
+    lines.push(
+      `
+${renamed} key(s) look renamed. The setting they were meant to carry is unset,
+which usually means a default is in force that nobody chose.`
+    );
+  }
+  lines.push(`
+FAIL \u2014 ${result.findings.length} finding(s).`);
+  return lines.join("\n");
+}
+var ORDER, LABELS;
+var init_env_check = __esm({
+  "src/env-check.ts"() {
+    ORDER = [
+      "renamed",
+      "missing",
+      "empty",
+      "malformed",
+      "duplicate",
+      "unknown"
+    ];
+    LABELS = {
+      renamed: "Renamed \u2014 set under a name nothing reads",
+      missing: "Missing",
+      empty: "Present but empty",
+      malformed: "Malformed line",
+      duplicate: "Set more than once",
+      unknown: "Unknown \u2014 not in the example"
+    };
+  }
+});
+
 // src/skills.ts
 function isSafeSkillSlug(slug) {
   return slug !== "." && slug !== ".." && /^[A-Za-z0-9._-]+$/.test(slug);
 }
 
 // src/cli.ts
+var BREAK = "\n";
 var DEFAULT_SOURCE = "https://olwiba.com/skills/manifest.json";
 var [command, subcommand] = process.argv.slice(2);
 if (command === "skills" && subcommand === "install") {
@@ -2376,6 +2511,8 @@ if (command === "skills" && subcommand === "install") {
   await runAsciiGif();
 } else if (command === "generate-assets") {
   await runGenerateAssets();
+} else if (command === "env-check" || command === "env") {
+  process.exitCode = await runEnvCheck();
 } else {
   process.stdout.write(
     "Usage:\n  dx skills install [--source <url>] [--target claude|amp] [--all] [--name a,b,c]\n  dx worktree cleanup [repo-name-or-path] [--repos-root <path>] [--remote <name>] [--dry-run] [--force] [--no-fetch]\n  dx ascii-gif --text <text> --out <file.gif>\n  dx generate-assets --name <app> --icon <lucide-icon> --color <#hex> [--out <dir>] [--og-component <svg-or-image-path>]\n"
@@ -2597,3 +2734,47 @@ function parseNumberFlag(value) {
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : void 0;
 }
+async function runEnvCheck() {
+  const { readFileSync: readFileSync3, existsSync: existsSync2 } = await import('fs');
+  const { checkEnv: checkEnv2, formatEnvReport: formatEnvReport2 } = await Promise.resolve().then(() => (init_env_check(), env_check_exports));
+  const flags = parseFlags(process.argv.slice(3));
+  const examplePath = flags.example ?? ".env.example";
+  if (!existsSync2(examplePath)) {
+    process.stderr.write(
+      `No example file at ${examplePath}.${BREAK}It is the schema this compares against; pass --example to point elsewhere.` + BREAK
+    );
+    return 1;
+  }
+  const example = readFileSync3(examplePath, "utf8");
+  let actual;
+  if (flags.file) {
+    if (!existsSync2(flags.file)) {
+      process.stderr.write(`No environment file at ${flags.file}.${BREAK}`);
+      return 1;
+    }
+    actual = readFileSync3(flags.file, "utf8");
+  } else {
+    if (stdin.isTTY) {
+      process.stdout.write(
+        `Paste the environment below, then press ${process.platform === "win32" ? "Ctrl+Z and Enter" : "Ctrl+D"}.${BREAK}Nothing is stored or transmitted.` + BREAK + BREAK
+      );
+    }
+    actual = await readAllStdin();
+    if (actual.trim() === "") {
+      process.stderr.write("Nothing to check. Pass --file <path> or paste an environment." + BREAK);
+      return 1;
+    }
+  }
+  const result = checkEnv2({
+    example,
+    actual,
+    optional: flags.optional ? flags.optional.split(",").map((key) => key.trim()).filter(Boolean) : []
+  });
+  process.stdout.write(`${formatEnvReport2(result)}${BREAK}`);
+  return result.findings.length > 0 ? 1 : 0;
+}
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}

package/dist/env-check.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Compares a real environment against the example that documents it.
+ *
+ * Pure string comparison, deliberately. The input is a file full of live
+ * credentials, so it is never sent anywhere, never written to disk, and never
+ * echoed back — the report names keys and says nothing about values.
+ *
+ * `.env.example` is the schema. Every repository already has one, which is what
+ * makes this usable outside the repositories that have a typed schema, and
+ * those are exactly the ones where environments have been rotting unnoticed.
+ */
+type EnvFinding = {
+    kind: 'missing';
+    key: string;
+} | {
+    kind: 'unknown';
+    key: string;
+} | {
+    kind: 'renamed';
+    key: string;
+    looksLike: string;
+} | {
+    kind: 'empty';
+    key: string;
+} | {
+    kind: 'malformed';
+    line: number;
+    text: string;
+} | {
+    kind: 'duplicate';
+    key: string;
+};
+interface EnvCheckResult {
+    findings: EnvFinding[];
+    /** Keys present in both, non-empty. Counted, never listed. */
+    okCount: number;
+    exampleCount: number;
+    actualCount: number;
+}
+interface ParsedEnv {
+    /** Key to whether it has a non-empty value. Values themselves are discarded. */
+    keys: Map<string, boolean>;
+    duplicates: string[];
+    malformed: Array<{
+        line: number;
+        text: string;
+    }>;
+}
+/**
+ * Reads keys and discards values immediately.
+ *
+ * The value never leaves this function, so nothing downstream can leak one by
+ * accident — including a future change to the report format.
+ */
+declare function parseEnv(source: string): ParsedEnv;
+declare function checkEnv({ example, actual, 
+/** Keys allowed to be absent, e.g. optional credentials. */
+optional, }: {
+    example: string;
+    actual: string;
+    optional?: string[];
+}): EnvCheckResult;
+/** Formats a report. Contains key names and counts only, never a value. */
+declare function formatEnvReport(result: EnvCheckResult): string;
+
+export { type EnvCheckResult, type EnvFinding, checkEnv, formatEnvReport, parseEnv };

package/dist/env-check.js

@@ -0,0 +1,126 @@
+// src/env-check.ts
+function parseEnv(source) {
+  const keys = /* @__PURE__ */ new Map();
+  const duplicates = [];
+  const malformed = [];
+  source.split(/\r?\n/).forEach((raw, index) => {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) return;
+    const withoutExport = line.replace(/^export\s+/, "");
+    const eq = withoutExport.indexOf("=");
+    if (eq <= 0) {
+      malformed.push({ line: index + 1, text: withoutExport.slice(0, 24) });
+      return;
+    }
+    const key = withoutExport.slice(0, eq).trim();
+    const value = withoutExport.slice(eq + 1).trim();
+    if (keys.has(key)) duplicates.push(key);
+    keys.set(key, value !== "" && value !== '""' && value !== "''");
+  });
+  return { keys, duplicates, malformed };
+}
+function findRenameCandidate(unknownKey, knownKeys) {
+  const normalise = (key) => key.replace(/[^A-Z0-9]/gi, "").toUpperCase();
+  const target = normalise(unknownKey);
+  return knownKeys.find((known) => {
+    const candidate = normalise(known);
+    if (candidate === target) return true;
+    return candidate.length >= 6 && (target.endsWith(candidate) || target.startsWith(candidate));
+  });
+}
+function checkEnv({
+  example,
+  actual,
+  /** Keys allowed to be absent, e.g. optional credentials. */
+  optional = []
+}) {
+  const exampleEnv = parseEnv(example);
+  const actualEnv = parseEnv(actual);
+  const optionalSet = new Set(optional);
+  const exampleKeys = [...exampleEnv.keys.keys()];
+  const findings = [];
+  let okCount = 0;
+  for (const key of exampleKeys) {
+    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;
+    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;
+    if (!actualEnv.keys.has(key)) {
+      if (!isOptional) findings.push({ kind: "missing", key });
+      continue;
+    }
+    const hasValue = actualEnv.keys.get(key) === true;
+    if (!hasValue && !isOptional) {
+      findings.push({ kind: "empty", key });
+      continue;
+    }
+    okCount += 1;
+  }
+  for (const key of actualEnv.keys.keys()) {
+    if (exampleEnv.keys.has(key)) continue;
+    const looksLike = findRenameCandidate(key, exampleKeys);
+    findings.push(looksLike ? { kind: "renamed", key, looksLike } : { kind: "unknown", key });
+  }
+  for (const key of actualEnv.duplicates) findings.push({ kind: "duplicate", key });
+  for (const line of actualEnv.malformed) findings.push({ kind: "malformed", ...line });
+  return {
+    findings,
+    okCount,
+    exampleCount: exampleEnv.keys.size,
+    actualCount: actualEnv.keys.size
+  };
+}
+var ORDER = [
+  "renamed",
+  "missing",
+  "empty",
+  "malformed",
+  "duplicate",
+  "unknown"
+];
+var LABELS = {
+  renamed: "Renamed \u2014 set under a name nothing reads",
+  missing: "Missing",
+  empty: "Present but empty",
+  malformed: "Malformed line",
+  duplicate: "Set more than once",
+  unknown: "Unknown \u2014 not in the example"
+};
+function formatEnvReport(result) {
+  const lines = [];
+  lines.push(
+    `  ${result.actualCount} keys checked against ${result.exampleCount} in the example, ${result.okCount} correct`
+  );
+  if (result.findings.length === 0) {
+    lines.push("\nPASS \u2014 environment matches the example.");
+    return lines.join("\n");
+  }
+  for (const kind of ORDER) {
+    const group = result.findings.filter((finding) => finding.kind === kind);
+    if (group.length === 0) continue;
+    lines.push(`
+${LABELS[kind]}:`);
+    for (const finding of group) {
+      if (finding.kind === "renamed") {
+        lines.push(`  \u2717 ${finding.key}  \u2192  did you mean ${finding.looksLike}?`);
+      } else if (finding.kind === "malformed") {
+        lines.push(`  \u2717 line ${finding.line}: ${finding.text}\u2026`);
+      } else {
+        lines.push(`  \u2717 ${finding.key}`);
+      }
+    }
+  }
+  const renamed = result.findings.filter((finding) => finding.kind === "renamed").length;
+  if (renamed > 0) {
+    lines.push(
+      `
+${renamed} key(s) look renamed. The setting they were meant to carry is unset,
+which usually means a default is in force that nobody chose.`
+    );
+  }
+  lines.push(`
+FAIL \u2014 ${result.findings.length} finding(s).`);
+  return lines.join("\n");
+}
+
+export { checkEnv, formatEnvReport, parseEnv };
+//# sourceMappingURL=env-check.js.map
+//# sourceMappingURL=env-check.js.map

package/dist/env-check.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/env-check.ts"],"names":[],"mappings":"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","file":"env-check.js","sourcesContent":["/**\n * Compares a real environment against the example that documents it.\n *\n * Pure string comparison, deliberately. The input is a file full of live\n * credentials, so it is never sent anywhere, never written to disk, and never\n * echoed back — the report names keys and says nothing about values.\n *\n * `.env.example` is the schema. Every repository already has one, which is what\n * makes this usable outside the repositories that have a typed schema, and\n * those are exactly the ones where environments have been rotting unnoticed.\n */\n\nexport type EnvFinding =\n  | { kind: 'missing'; key: string }\n  | { kind: 'unknown'; key: string }\n  | { kind: 'renamed'; key: string; looksLike: string }\n  | { kind: 'empty'; key: string }\n  | { kind: 'malformed'; line: number; text: string }\n  | { kind: 'duplicate'; key: string };\n\nexport interface EnvCheckResult {\n  findings: EnvFinding[];\n  /** Keys present in both, non-empty. Counted, never listed. */\n  okCount: number;\n  exampleCount: number;\n  actualCount: number;\n}\n\ninterface ParsedEnv {\n  /** Key to whether it has a non-empty value. Values themselves are discarded. */\n  keys: Map<string, boolean>;\n  duplicates: string[];\n  malformed: Array<{ line: number; text: string }>;\n}\n\n/**\n * Reads keys and discards values immediately.\n *\n * The value never leaves this function, so nothing downstream can leak one by\n * accident — including a future change to the report format.\n */\nexport function parseEnv(source: string): ParsedEnv {\n  const keys = new Map<string, boolean>();\n  const duplicates: string[] = [];\n  const malformed: Array<{ line: number; text: string }> = [];\n\n  source.split(/\\r?\\n/).forEach((raw, index) => {\n    const line = raw.trim();\n    if (line === '' || line.startsWith('#')) return;\n\n    // `export FOO=bar` is valid in a shell-sourced file.\n    const withoutExport = line.replace(/^export\\s+/, '');\n    const eq = withoutExport.indexOf('=');\n\n    if (eq <= 0) {\n      // Reported by line number without the text where it could hold a value:\n      // a line missing its `=` may still be a pasted secret.\n      malformed.push({ line: index + 1, text: withoutExport.slice(0, 24) });\n      return;\n    }\n\n    const key = withoutExport.slice(0, eq).trim();\n    const value = withoutExport.slice(eq + 1).trim();\n\n    if (keys.has(key)) duplicates.push(key);\n    // A later assignment wins in most loaders, so the last one decides.\n    keys.set(key, value !== '' && value !== '\"\"' && value !== \"''\");\n  });\n\n  return { keys, duplicates, malformed };\n}\n\n/**\n * Whether an unrecognised key looks like a renamed version of a known one.\n *\n * This is the finding that matters. A stale key reads as configured — someone\n * scanning the file sees the name they expect in all but a prefix and stops\n * looking — so reporting it as a generic unknown would not tell anyone that the\n * setting it was meant to carry is unset.\n */\nfunction findRenameCandidate(unknownKey: string, knownKeys: string[]): string | undefined {\n  const normalise = (key: string) => key.replace(/[^A-Z0-9]/gi, '').toUpperCase();\n  const target = normalise(unknownKey);\n\n  return knownKeys.find((known) => {\n    const candidate = normalise(known);\n    if (candidate === target) return true;\n    // A prefix or suffix on an otherwise identical name: VITE_FOO against FOO.\n    return (\n      candidate.length >= 6 &&\n      (target.endsWith(candidate) || target.startsWith(candidate))\n    );\n  });\n}\n\nexport function checkEnv({\n  example,\n  actual,\n  /** Keys allowed to be absent, e.g. optional credentials. */\n  optional = [],\n}: {\n  example: string;\n  actual: string;\n  optional?: string[];\n}): EnvCheckResult {\n  const exampleEnv = parseEnv(example);\n  const actualEnv = parseEnv(actual);\n  const optionalSet = new Set(optional);\n\n  const exampleKeys = [...exampleEnv.keys.keys()];\n  const findings: EnvFinding[] = [];\n  let okCount = 0;\n\n  for (const key of exampleKeys) {\n    // A blank in the example is the example saying this slot is optional — it\n    // is showing the name without claiming a value belongs there. Absent then\n    // means the same as blank, and reporting it drowns the real findings in\n    // unset credentials for services this deployment does not use.\n    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;\n    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;\n\n    if (!actualEnv.keys.has(key)) {\n      if (!isOptional) findings.push({ kind: 'missing', key });\n      continue;\n    }\n\n    const hasValue = actualEnv.keys.get(key) === true;\n\n    // Blank where the example shows a value: the example is demonstrating that\n    // something belongs there. Blank in both is a deliberate opt-out.\n    if (!hasValue && !isOptional) {\n      findings.push({ kind: 'empty', key });\n      continue;\n    }\n\n    okCount += 1;\n  }\n\n  for (const key of actualEnv.keys.keys()) {\n    if (exampleEnv.keys.has(key)) continue;\n\n    const looksLike = findRenameCandidate(key, exampleKeys);\n    findings.push(looksLike ? { kind: 'renamed', key, looksLike } : { kind: 'unknown', key });\n  }\n\n  for (const key of actualEnv.duplicates) findings.push({ kind: 'duplicate', key });\n  for (const line of actualEnv.malformed) findings.push({ kind: 'malformed', ...line });\n\n  return {\n    findings,\n    okCount,\n    exampleCount: exampleEnv.keys.size,\n    actualCount: actualEnv.keys.size,\n  };\n}\n\nconst ORDER: EnvFinding['kind'][] = [\n  'renamed',\n  'missing',\n  'empty',\n  'malformed',\n  'duplicate',\n  'unknown',\n];\n\nconst LABELS: Record<EnvFinding['kind'], string> = {\n  renamed: 'Renamed — set under a name nothing reads',\n  missing: 'Missing',\n  empty: 'Present but empty',\n  malformed: 'Malformed line',\n  duplicate: 'Set more than once',\n  unknown: 'Unknown — not in the example',\n};\n\n/** Formats a report. Contains key names and counts only, never a value. */\nexport function formatEnvReport(result: EnvCheckResult): string {\n  const lines: string[] = [];\n  lines.push(\n    `  ${result.actualCount} keys checked against ${result.exampleCount} in the example, ${result.okCount} correct`,\n  );\n\n  if (result.findings.length === 0) {\n    lines.push('\\nPASS — environment matches the example.');\n    return lines.join('\\n');\n  }\n\n  for (const kind of ORDER) {\n    const group = result.findings.filter((finding) => finding.kind === kind);\n    if (group.length === 0) continue;\n\n    lines.push(`\\n${LABELS[kind]}:`);\n    for (const finding of group) {\n      if (finding.kind === 'renamed') {\n        lines.push(`  ✗ ${finding.key}  →  did you mean ${finding.looksLike}?`);\n      } else if (finding.kind === 'malformed') {\n        lines.push(`  ✗ line ${finding.line}: ${finding.text}…`);\n      } else {\n        lines.push(`  ✗ ${finding.key}`);\n      }\n    }\n  }\n\n  // Renames are called out because they are the ones that read as configured.\n  const renamed = result.findings.filter((finding) => finding.kind === 'renamed').length;\n  if (renamed > 0) {\n    lines.push(\n      `\\n${renamed} key(s) look renamed. The setting they were meant to carry is unset,` +\n        '\\nwhich usually means a default is in force that nobody chose.',\n    );\n  }\n\n  lines.push(`\\nFAIL — ${result.findings.length} finding(s).`);\n  return lines.join('\\n');\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/dx",
-  "version": "0.0.24",
+  "version": "0.0.28",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -39,6 +39,10 @@
     "./generate-assets": {
       "import": "./dist/generate-assets.js",
       "types": "./dist/generate-assets.d.ts"
+    },
+    "./env-check": {
+      "import": "./dist/env-check.js",
+      "types": "./dist/env-check.d.ts"
     }
   },
   "files": [