vibecodedshit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,95 @@
+Copyright 2026 Peter Kisel
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# health
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Codebase Health benchmark. See `methodology/v1.0/METHODOLOGY.md` for how scores work.
+
+## Run it with npx
+
+```
+npx vibecodedshit scan .
+```
+
+Needs Node 22 or later and `git`. No clone, no plugin, no repository access for anyone. With Docker and the `health:1.0` image the scan is a full run. Without them it falls back to a preview scan, prints why and which parameters it skipped (they need Docker), and writes `run.json`. The scan runs on your machine. Your code is not uploaded; it only looks up your dependencies' names and versions on the public npm and PyPI registries (and OSV, if osv-scanner is installed). To get the full run, build the image with `docker build -t health:1.0 -f <package>/docker/Dockerfile <package>/docker` (the scan prints the exact command).
+
+Submitting is opt-in: `npx vibecodedshit submit run.json --email <you@example.com>` prints the payload and sends it only with `--confirm`. Only full, comparable runs can be submitted.
+
+## From a clone
+
+```
+npm install
+npm run health -- scan <path> --preview [--as-of YYYY-MM-DD] [--out run.json]
+```
+
+A preview scan runs the static layer only, measures every parameter that needs no execution (not 1.1 to 1.3, 2.1, 2.5, 6.1, 6.3) and writes a run.json marked "preview, not comparable". Without `--preview` the scan is a full run: install, build, typecheck, lint, the tests and every static analysis tool run in the pinned `health:1.0` image (`npm run image:build`, Docker needed, no other tool on the host), which adds 6.1, 2.1 and 2.5. A full run is not comparable until 1.1 to 1.3 and 6.3 are measured. Full runs keep the package managers' downloads in `~/.cache/health/packages` (or `$XDG_CACHE_HOME/health/packages`) so a second scan does not download them again. Set `HEALTH_PACKAGE_CACHE` to another directory, or to `off` to download everything on every scan.
+
+Needs Node 22 or later, `git`, and `python3` for repositories with Python files.
+
+## Claude Code plugin
+
+The CLI ships as a Claude Code plugin with a `/codebase-health` skill. The plugin root is this directory; the marketplace file is `.claude-plugin/marketplace.json` at the repository root.
+
+```
+/plugin marketplace add Raavn/vibecodedshit.com
+/plugin install codebase-health@vibecodedshit
+/codebase-health [path]
+```
+
+The namespaced form `/codebase-health:codebase-health` also works. The skill runs a full scan when Docker and the `health:1.0` image are available. When Docker is running but the image is missing, it builds the image in the background while it runs a preview scan, then runs the full scan. When Docker is missing or not running, it asks whether to run a preview scan, which is not comparable, or wait while you install or start Docker. It then renders the HTML report, and from the second scan of a repository on (same mode) a PNG card with the previous and new score and their bands, and explains `run.json`: the health score and band, the weakest dimension and the three parameters most worth fixing. Claude only reads the scores. It never computes or adjusts them, and it sends something only after you have seen the exact payload and said yes.
+
+## Codex plugin
+
+The same package ships as a Codex plugin. The manifest is `.codex-plugin/plugin.json` in this directory, the skill is `codex/skills/codebase-health/SKILL.md`, and the marketplace file is `.agents/plugins/marketplace.json` at the repository root. It runs the same `dist/bin.js`, `health:1.0` image and methodology as the Claude Code plugin, and submits through the same API.
+
+```
+codex plugin marketplace add Raavn/vibecodedshit.com
+```
+
+Then install codebase-health from the Plugins Directory and run `$codebase-health [path]`. Update with `codex plugin marketplace upgrade vibecodedshit`. Runs and checkouts are kept in `${CODEX_HOME:-~/.codex}/codebase-health/`.
+
+## Submitting a result
+
+Submission is opt-in. `health submit <run.json> --email <addr> [--confirm] [--newsletter] [--include-repo-name] [--summary-file <path>]` prints the full payload and sends it to app.vibecodedshit.com only with `--confirm`. The skill shows the payload and asks, with No as the default. Privacy page: https://app.vibecodedshit.com/privacy
+
+- The repository is identified by the SHA-256 of its normalised git remote URL (the root commit when there is no remote). The name is sent only with `--include-repo-name`.
+- The email is required. It is used for your rank, for methodology version notices, and for the newsletter only with `--newsletter`.
+- The CLI prints your rank and the score needed for the top 10 on that methodology version. Nobody else's scores are published.
+- Only a comparable full run can be submitted. Source code and file paths are never sent.
+- The first email to submit a repository on a methodology version owns its entry; a different email gets a 409. The owner can re-submit to replace it, if the new run's as-of date is not earlier.
+- Exit codes: 0 printed or sent, 1 usage error or refusal, 6 sending failed.
+
+Installing by the GitHub slug works only for users whose git credentials can read the repository.
+
+Development: `dist/` is committed because plugin installs don't run a build. Run `npm run build` and commit `dist/` with any change under `src/`. `npm run verify` fails if `dist/` is stale. When you bump `version` in `package.json`, bump it in `.claude-plugin/plugin.json` too.
+
+## Publishing
+
+The package is `vibecodedshit` (public, Elastic-2.0). To release: bump `version` in `package.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` and `../version.json` together, then run `npm publish`. `prepublishOnly` builds `dist/` and runs `npm run verify`. Check the tarball first with `npm pack --dry-run`. Publishing needs an npm login with 2FA.

package/assets/fonts/NotoEmoji-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2013 Google LLC
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/SpaceGrotesk-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+const code = await run(process.argv.slice(2), {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    cwd: process.cwd(),
+});
+process.exitCode = code;

package/dist/card/previous.js

@@ -0,0 +1,38 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { readRun, RunReadError } from '../run/read.js';
+/**
+ * The newest `<historyDir>/<dir>/run.json` written before `currentFile` for the same repository path, methodology version
+ * and mode, valid and with a health score. Runs from other versions are never compared, and a preview next to a full run
+ * would compare different parameters. Unreadable files are skipped.
+ */
+export function findPreviousRun(currentFile, current, historyDir) {
+    const before = statSync(currentFile).mtimeMs;
+    let best = null;
+    for (const entry of readdirSync(historyDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(historyDir, entry.name, 'run.json');
+        if (!existsSync(file))
+            continue;
+        // The current run is never older than itself, so this also skips it.
+        const mtime = statSync(file).mtimeMs;
+        if (mtime >= before || (best && mtime <= best.mtime))
+            continue;
+        let run;
+        try {
+            run = readRun(file);
+        }
+        catch (err) {
+            if (err instanceof RunReadError)
+                continue;
+            throw err;
+        }
+        if (!run.valid || run.health === null)
+            continue;
+        if (run.repo.path !== current.repo.path || run.methodology.version !== current.methodology.version || run.mode !== current.mode)
+            continue;
+        best = { file, health: run.health, mtime };
+    }
+    return best && { file: best.file, health: best.health };
+}

package/dist/card/render.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { initWasm, Resvg } from '@resvg/resvg-wasm';
+import { packageRoot } from '../methodology/load.js';
+import { escapeHtml as e } from '../report/escape.js';
+const WIDTH = 1200;
+const HEIGHT = 630;
+const BACKGROUND = '#CEA5C7';
+const FOREGROUND = '#471044';
+const FONT = 'Space Grotesk';
+// The brand replaces every "i" with 💩; the Noto Emoji subset supplies that one glyph.
+const BRAND = 'V\u{1F4A9}becodedsh\u{1F4A9}t.com';
+const HEADER_SIZE = 44;
+const HEADER_MAX_WIDTH = WIDTH - 2 * 60;
+const SCORE_SIZE = 240;
+const TIER_SIZE = 32;
+const TIER_SPACING = 6;
+const PILL_HEIGHT = 64;
+const PILL_PADDING = 28;
+function column(x, side, measure, filled) {
+    const tier = side.tier.toUpperCase();
+    const pill = Math.round(measure(tier, TIER_SIZE, TIER_SPACING)) + 2 * PILL_PADDING;
+    const outline = filled ? `fill="${FOREGROUND}"` : `fill="none" stroke="${FOREGROUND}" stroke-width="3"`;
+    return [
+        `<text x="${x}" y="400" font-size="${SCORE_SIZE}" text-anchor="middle" fill="${FOREGROUND}">${e(side.score)}</text>`,
+        `<rect x="${x - pill / 2}" y="452" width="${pill}" height="${PILL_HEIGHT}" rx="${PILL_HEIGHT / 2}" ${outline}/>`,
+        `<text x="${x}" y="495" font-size="${TIER_SIZE}" letter-spacing="${TIER_SPACING}" text-anchor="middle" fill="${filled ? BACKGROUND : FOREGROUND}">${e(tier)}</text>`,
+    ].join('');
+}
+/** The card as SVG: the brand and repository, then the earlier score, an arrow and the new score, each with its tier below. */
+export function cardSvg(card, measure) {
+    const header = `${BRAND} report for ${card.repo}`;
+    const width = measure(header, HEADER_SIZE, 0);
+    // A long repository name shrinks the header instead of running off the card.
+    const headerSize = width > HEADER_MAX_WIDTH ? Math.floor((HEADER_SIZE * HEADER_MAX_WIDTH) / width) : HEADER_SIZE;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}" font-family="${FONT}" font-weight="700">`,
+        `<rect width="${WIDTH}" height="${HEIGHT}" fill="${BACKGROUND}"/>`,
+        `<text x="${WIDTH / 2}" y="110" font-size="${headerSize}" text-anchor="middle" fill="${FOREGROUND}">${e(header)}</text>`,
+        column(300, card.before, measure, false),
+        `<text x="${WIDTH / 2}" y="346" font-size="120" text-anchor="middle" fill="${FOREGROUND}">→</text>`,
+        column(900, card.after, measure, true),
+        '</svg>',
+    ].join('');
+}
+let wasm;
+let fonts;
+function options() {
+    fonts ??= ['SpaceGrotesk-Bold.ttf', 'NotoEmoji-Poop.ttf'].map((name) => readFileSync(path.join(packageRoot, 'assets', 'fonts', name)));
+    return { font: { fontBuffers: fonts, defaultFontFamily: FONT } };
+}
+function measure(text, fontSize, letterSpacing) {
+    const probe = new Resvg(`<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><text font-family="${FONT}" font-weight="700" font-size="${fontSize}" letter-spacing="${letterSpacing}">${e(text)}</text></svg>`, options());
+    const box = probe.getBBox();
+    const width = box?.width ?? 0;
+    box?.free();
+    probe.free();
+    return width;
+}
+/** Render the card to a PNG with the bundled fonts only, so it looks the same on every machine. */
+export async function renderCard(card) {
+    wasm ??= initWasm(readFileSync(createRequire(import.meta.url).resolve('@resvg/resvg-wasm/index_bg.wasm')));
+    await wasm;
+    const resvg = new Resvg(cardSvg(card, measure), options());
+    const image = resvg.render();
+    const png = image.asPng();
+    image.free();
+    resvg.free();
+    return png;
+}

package/dist/cli.js

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { runCard } from './commands/card.js';
+import { EXIT } from './commands/common.js';
+import { runDiff } from './commands/diff.js';
+import { footer, imageBuildCommand } from './commands/footer.js';
+import { imageDigest } from './exec/docker.js';
+import { runReport } from './commands/report.js';
+import { runRoute } from './commands/route.js';
+import { runSubmit } from './commands/submit.js';
+import { summarize } from './commands/summary.js';
+import { CURRENT_METHODOLOGY_VERSION, loadMethodology, MethodologyError, packageRoot } from './methodology/load.js';
+import { invalidRun, NoLogicFilesError, runScan } from './run/scan.js';
+import { writeRun } from './run/write.js';
+import { NotAGitRepositoryError } from './scope/build.js';
+import { ToolError } from './scope/types.js';
+export { EXIT } from './commands/common.js';
+export { summarize } from './commands/summary.js';
+const USAGE = `Usage: vibecodedshit scan <path> [--preview] [--as-of YYYY-MM-DD] [--out <file>] [--methodology <version>]
+       vibecodedshit report <run.json> [--out <file>]
+       vibecodedshit diff <before.json> <after.json> [--json]
+       vibecodedshit route <run.json> --out <dir>
+       vibecodedshit route --check <dir> <run.json>
+       vibecodedshit card <run.json> --history <dir> [--out <file>]
+       vibecodedshit submit <run.json> --email <addr> [--confirm] [--newsletter] [--include-repo-name] [--summary-file <path>]
+
+Exit codes: 0 ok, 1 usage or unreadable input, 2 methodology error, 3 no logic file, 4 tool error, 5 diff refused, 6 submit failed.
+`;
+export async function run(argv, io, deps = {}) {
+    if (argv[0] === 'report')
+        return runReport(argv.slice(1), io);
+    if (argv[0] === 'diff')
+        return runDiff(argv.slice(1), io);
+    if (argv[0] === 'route')
+        return runRoute(argv.slice(1), io);
+    if (argv[0] === 'card')
+        return runCard(argv.slice(1), io);
+    if (argv[0] === 'submit')
+        return runSubmit(argv.slice(1), io, { git: deps.git, fetch: deps.fetch });
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                preview: { type: 'boolean' },
+                'as-of': { type: 'string' },
+                out: { type: 'string' },
+                methodology: { type: 'string' },
+            },
+        });
+    }
+    catch (err) {
+        io.stderr(`${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const [command, target] = parsed.positionals;
+    if (command !== 'scan' || !target || parsed.positionals.length > 2) {
+        io.stderr(USAGE);
+        return EXIT.usage;
+    }
+    const asOf = parsed.values['as-of'] ?? new Date().toISOString().slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(asOf) || Number.isNaN(Date.parse(asOf))) {
+        io.stderr(`--as-of must be a date like 2026-10-04, got "${asOf}"\n`);
+        return EXIT.usage;
+    }
+    const opts = {
+        repoPath: path.resolve(io.cwd, target),
+        methodologyVersion: parsed.values.methodology ?? CURRENT_METHODOLOGY_VERSION,
+        mode: parsed.values.preview ? 'preview' : 'full',
+        asOf,
+        ...deps,
+    };
+    const outFile = path.resolve(io.cwd, parsed.values.out ?? 'run.json');
+    let methodology;
+    try {
+        methodology = loadMethodology(opts.methodologyVersion);
+    }
+    catch (err) {
+        if (err instanceof MethodologyError) {
+            io.stderr(`Methodology error: ${err.message}\n`);
+            return EXIT.methodology;
+        }
+        throw err;
+    }
+    if (opts.mode === 'full' && !deps.execRunner && deps.imageDigest === undefined) {
+        // No Docker, or no usable image: fall back to the static layer so `scan .` works from an npx install.
+        const tag = methodology.execution.runner.image;
+        try {
+            opts.imageDigest = await imageDigest(tag);
+        }
+        catch (err) {
+            if (!(err instanceof ToolError))
+                throw err;
+            opts.mode = 'preview';
+            io.stderr(`${err.message}\nRunning a preview scan (static layer only, not comparable). For a full run: ${imageBuildCommand(packageRoot, tag)}\n`);
+        }
+    }
+    try {
+        const result = await runScan(opts, methodology);
+        writeRun(outFile, result);
+        io.stdout(summarize(result, methodology) + footer(result, outFile));
+        return EXIT.ok;
+    }
+    catch (err) {
+        if (err instanceof NoLogicFilesError) {
+            io.stderr(`${err.message}\n`);
+            return EXIT.noLogic;
+        }
+        if (err instanceof NotAGitRepositoryError) {
+            io.stderr(`${err.message}\n`);
+            return EXIT.usage;
+        }
+        if (err instanceof ToolError) {
+            writeRun(outFile, invalidRun(opts, err.message));
+            io.stderr(`Tool error: ${err.message}\n`);
+            return EXIT.tool;
+        }
+        throw err;
+    }
+}

package/dist/commands/card.js

@@ -0,0 +1,69 @@
+import { existsSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { findPreviousRun } from '../card/previous.js';
+import { renderCard } from '../card/render.js';
+import { loadMethodology, MethodologyError } from '../methodology/load.js';
+import { readRun, RunReadError } from '../run/read.js';
+import { EXIT } from './common.js';
+const CARD_USAGE = 'Usage: vibecodedshit card <run.json> --history <dir> [--out <file>]\n';
+function side(health, methodology) {
+    return { score: health.displayed, tier: methodology.bands.find((b) => b.key === health.band)?.name ?? health.band };
+}
+/** Writes a PNG card comparing a run with the previous run of the same repository in `--history`. No previous run, no card. */
+export async function runCard(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, allowPositionals: true, options: { out: { type: 'string' }, history: { type: 'string' } } });
+    }
+    catch (err) {
+        io.stderr(`${err instanceof Error ? err.message : String(err)}\n${CARD_USAGE}`);
+        return EXIT.usage;
+    }
+    const [input] = parsed.positionals;
+    const history = parsed.values.history;
+    if (!input || !history || parsed.positionals.length > 1) {
+        io.stderr(CARD_USAGE);
+        return EXIT.usage;
+    }
+    const historyDir = path.resolve(io.cwd, history);
+    if (!existsSync(historyDir) || !statSync(historyDir).isDirectory()) {
+        io.stderr(`--history ${historyDir}: not a directory\n`);
+        return EXIT.usage;
+    }
+    // The default is the current directory, never the scanned repository, the same rule as run.json.
+    const outFile = path.resolve(io.cwd, parsed.values.out ?? 'health-card.png');
+    try {
+        const file = path.resolve(io.cwd, input);
+        const run = readRun(file);
+        if (!run.valid) {
+            io.stderr(`run.json is invalid: ${run.invalidReason ?? 'no reason given'}\n`);
+            return EXIT.usage;
+        }
+        if (run.health === null) {
+            io.stderr('No card: the run has no health score.\n');
+            return EXIT.ok;
+        }
+        const previous = findPreviousRun(file, run, historyDir);
+        if (!previous) {
+            io.stderr(`No card: no earlier ${run.mode} run of ${run.repo.path} for methodology ${run.methodology.version} in ${historyDir}.\n`);
+            return EXIT.ok;
+        }
+        const methodology = loadMethodology(run.methodology.version);
+        const card = { repo: path.basename(run.repo.path), before: side(previous.health, methodology), after: side(run.health, methodology) };
+        writeFileSync(outFile, await renderCard(card));
+        io.stdout(`${outFile}\n`);
+        return EXIT.ok;
+    }
+    catch (err) {
+        if (err instanceof RunReadError) {
+            io.stderr(`${err.message}\n`);
+            return EXIT.usage;
+        }
+        if (err instanceof MethodologyError) {
+            io.stderr(`Methodology error: ${err.message}\n`);
+            return EXIT.methodology;
+        }
+        throw err;
+    }
+}