@davidvornholt/standards 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -74,13 +74,14 @@ type Source = {
   readonly cleanup: () => void;
 };
 
-type Command = 'check' | 'doctor' | 'github' | 'init' | 'sync';
+type Command = 'check' | 'doctor' | 'github' | 'help' | 'init' | 'sync';
 
 type CliOptions = {
-  readonly command: Command;
+  readonly command: Command | undefined;
   readonly consumer: string;
   readonly dryRun: boolean;
   readonly from: string | undefined;
+  readonly ref: string | undefined;
   readonly apply: boolean;
 };
 
@@ -163,9 +164,15 @@ const writeLock = async (dir: string, lock: Lock): Promise<void> => {
 
 // Fetch the template into a working directory. Accepts a local path (used to
 // prove the engine before the public repo exists and in tests), a github:
-// shorthand, or any git URL.
-const resolveSource = (src: string): Source => {
+// shorthand, or any git URL. Remote sources default to `main`; `ref` pins a
+// tag, branch, or full commit sha instead (`git fetch` accepts all three).
+const resolveSource = (src: string, ref: string | undefined): Source => {
   if (existsSync(src)) {
+    if (ref !== undefined) {
+      throw new Error(
+        `--ref requires a git URL source; a local path is used as-is: ${src}`,
+      );
+    }
     let sha = 'local';
     try {
       sha = execFileSync('git', ['-C', src, 'rev-parse', 'HEAD'], {
@@ -180,18 +187,34 @@ const resolveSource = (src: string): Source => {
   const url = src.startsWith(GITHUB_PREFIX)
     ? `https://github.com/${src.slice(GITHUB_PREFIX.length)}.git`
     : src;
+  const target = ref ?? 'main';
   const dir = mkdtempSync(join(tmpdir(), 'standards-'));
-  execFileSync('git', ['clone', '--depth', '1', '--branch', 'main', url, dir], {
-    stdio: 'ignore',
-  });
+  const cleanup = (): void => rmSync(dir, { recursive: true, force: true });
+  try {
+    // init + fetch instead of `clone --branch` so a full commit sha works as a
+    // ref, not only tags and branches (GitHub serves reachable sha fetches).
+    execFileSync('git', ['init', '--quiet', dir], { stdio: 'ignore' });
+    execFileSync(
+      'git',
+      ['-C', dir, 'fetch', '--quiet', '--depth', '1', '--', url, target],
+      { stdio: 'ignore' },
+    );
+    execFileSync(
+      'git',
+      ['-C', dir, 'checkout', '--quiet', '--detach', 'FETCH_HEAD'],
+      { stdio: 'ignore' },
+    );
+  } catch (error) {
+    cleanup();
+    throw new Error(
+      `Cannot fetch "${target}" from ${url}; expected a tag, branch, or full commit sha reachable on the remote`,
+      { cause: error },
+    );
+  }
   const sha = execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], {
     encoding: 'utf8',
   }).trim();
-  return {
-    dir,
-    sha,
-    cleanup: () => rmSync(dir, { recursive: true, force: true }),
-  };
+  return { dir, sha, cleanup };
 };
 
 // Recursively collect files under `abs`, keyed by their POSIX path relative to
@@ -461,7 +484,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
     );
     console.error(problems.join('\n'));
     console.error(
-      'These files are read-only. Restore them with `just sync-standards`, or move your change upstream.',
+      'These files are read-only. Restore them with `bun standards sync`, or move your change upstream.',
     );
     return false;
   }
@@ -474,15 +497,6 @@ const runCheck = async (consumer: string): Promise<boolean> => {
 const readTextIfPresent = async (path: string): Promise<string | null> =>
   existsSync(path) ? readFile(path, 'utf8') : null;
 
-const hasStandardsImport = (justfile: string): boolean =>
-  justfile.split('\n').some((line) => {
-    const trimmed = line.trim();
-    return (
-      trimmed === "import 'standards.just'" ||
-      trimmed === 'import "standards.just"'
-    );
-  });
-
 const DEPENDABOT_BASELINE_ECOSYSTEMS = ['bun', 'github-actions'] as const;
 const DEPENDABOT_SCHEDULE_INTERVALS = new Set([
   'daily',
@@ -679,11 +693,6 @@ const inspectPackageJson = (packageRaw: string): ReadonlyArray<string> => {
 
 const runDoctor = async (consumer: string): Promise<boolean> => {
   const problems: Array<string> = [];
-  const justfile = await readTextIfPresent(join(consumer, 'justfile'));
-  if (justfile === null || !hasStandardsImport(justfile)) {
-    problems.push("justfile must import 'standards.just'");
-  }
-
   const biome = await readTextIfPresent(join(consumer, 'biome.jsonc'));
   if (biome === null || !biome.includes('"./biome.base.jsonc"')) {
     problems.push('biome.jsonc must extend "./biome.base.jsonc"');
@@ -735,11 +744,30 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
   return true;
 };
 
+const USAGE = `Usage: standards <command> [options]
+
+Commands:
+  init    Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
+  sync    Mirror canonical files from upstream and rewrite the lock
+  check   Verify canonical files, extension seams, and GitHub settings
+  doctor  Validate extension seams only
+  github  Compare (--check) or converge (--apply) live GitHub settings
+  help    Show this help
+
+Options:
+  --dir <path>   Consumer directory to operate on (default: current directory)
+  --from <src>   Upstream override for init/sync (GitHub repo or local path)
+  --ref <ref>    Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
+  --dry-run      Preview a sync without writing anything
+  --check        With github: compare live settings to the declaration (default)
+  --apply        With github: converge the live repository (needs admin auth)`;
+
 const commandFromArg = (arg: string): Command => {
   if (
     arg === 'check' ||
     arg === 'doctor' ||
     arg === 'github' ||
+    arg === 'help' ||
     arg === 'init' ||
     arg === 'sync'
   ) {
@@ -773,6 +801,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let consumer = process.cwd();
   let dryRun = false;
   let from: string | undefined;
+  let ref: string | undefined;
   let checkFlag = false;
   let apply = false;
 
@@ -796,15 +825,21 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
         from = nextOptionValue(argv, index);
         index += 1;
         break;
+      case '--ref':
+        ref = nextOptionValue(argv, index);
+        index += 1;
+        break;
+      case '--help':
+      case '-h':
+        command = setCommand(command, 'help');
+        break;
       default:
         command = setCommand(command, commandFromArg(arg));
     }
   }
 
-  // `--check` doubles as the legacy spelling of the check command and as the
-  // explicit (default) mode of `github`.
   if (checkFlag && command !== 'github') {
-    command = setCommand(command, 'check');
+    throw new Error('--check is only valid with the github command');
   }
   if (apply && command !== 'github') {
     throw new Error('--apply is only valid with the github command');
@@ -812,12 +847,16 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   if (apply && checkFlag) {
     throw new Error('github accepts exactly one of --check or --apply');
   }
+  if (ref !== undefined && command !== 'init' && command !== 'sync') {
+    throw new Error('--ref is only valid with the init and sync commands');
+  }
 
   return {
-    command: command ?? 'sync',
+    command,
     consumer: resolve(consumer),
     dryRun,
     from,
+    ref,
     apply,
   };
 };
@@ -837,18 +876,19 @@ const runCheckCommand = async (consumer: string): Promise<boolean> => {
 const runInitCommand = async (
   consumer: string,
   from: string | undefined,
+  ref: string | undefined,
 ): Promise<void> => {
   // Refuse before cloning upstream: re-initializing skips the lock, so it
   // would silently overwrite local canonical edits and orphan files that
   // upstream deleted (they leave the lock and no future sync removes them).
   if (existsSync(join(consumer, 'sync-standards.lock'))) {
     console.error(
-      'standards: already initialized (sync-standards.lock exists). Use `just sync-standards` to update.',
+      'standards: already initialized (sync-standards.lock exists). Use `bun standards sync` to update.',
     );
     process.exitCode = 1;
     return;
   }
-  const source = resolveSource(from ?? DEFAULT_UPSTREAM);
+  const source = resolveSource(from ?? DEFAULT_UPSTREAM, ref);
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -862,12 +902,13 @@ const runInitCommand = async (
 const runSyncCommand = async (
   consumer: string,
   from: string | undefined,
+  ref: string | undefined,
   dryRun: boolean,
 ): Promise<void> => {
   const consumerManifest = await loadManifest(
     join(consumer, 'sync-standards.json'),
   );
-  const source = resolveSource(from ?? consumerManifest.upstream);
+  const source = resolveSource(from ?? consumerManifest.upstream, ref);
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -879,10 +920,22 @@ const runSyncCommand = async (
 };
 
 const main = async (): Promise<void> => {
-  const { command, consumer, dryRun, from, apply } = parseArgs(
+  const { command, consumer, dryRun, from, ref, apply } = parseArgs(
     process.argv.slice(2),
   );
 
+  if (command === undefined) {
+    console.error('standards: a command is required\n');
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'help') {
+    console.log(USAGE);
+    return;
+  }
+
   if (command === 'check') {
     if (!(await runCheckCommand(consumer))) {
       process.exitCode = 1;
@@ -908,12 +961,12 @@ const main = async (): Promise<void> => {
   }
 
   if (command === 'init') {
-    await runInitCommand(consumer, from);
+    await runInitCommand(consumer, from, ref);
     return;
   }
 
   if (command === 'sync') {
-    await runSyncCommand(consumer, from, dryRun);
+    await runSyncCommand(consumer, from, ref, dryRun);
   }
 };
 

package/src/github-api.ts

@@ -99,7 +99,7 @@ export const loadDeclared = async (
     return {
       merged: null,
       problems: [
-        `${CANONICAL_SETTINGS_FILE} not found; run \`just sync-standards\` first`,
+        `${CANONICAL_SETTINGS_FILE} not found; run \`bun standards sync\` first`,
       ],
     };
   }

package/src/github-commands.ts

@@ -78,7 +78,7 @@ export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   if (problems.length > 0) {
     reportProblems(problems);
     console.error(
-      'Converge with `just sync-standards github --apply` (admin auth), or fix the declaration.',
+      'Converge with `bun standards github --apply` (admin auth), or fix the declaration.',
     );
     return false;
   }