@format.dev/cli 0.0.0 → 0.1.0

package/README.md

@@ -1,32 +1,41 @@
 # @format.dev/cli
 
-**This is a bootstrap placeholder. It reserves the package name and does nothing else.**
+This CLI exposes the `format` binary: the front door to Format. Install this package to scaffold projects, compile documents, and run the Studio dev server.
 
-Format is not released yet. Version `0.0.0` is not a usable version of this
-package: it contains no implementation, and installing it gets you an empty
-module.
+There are two key advantages to using the Format CLI.
 
-## Why it exists
+1. It pins all Format packages to a single version defined in your `format.config.json` and provides an interface to update or migrate to different versions in one command.
 
-npm binds a package’s trusted publisher, and its staged-publishing flow, to a
-package that already exists. Creating these names ahead of the first release is
-what lets every real release go out through a reviewed, credential-free
-workflow rather than through a token somebody holds.
+2. It runs `@format.dev/studio` and `@format.dev/compile` as transient dependencies that are run in memory when called on. For you this means less dependencies need to be installed at CI if they're not strictly needed.
 
-This version is published deliberately and deprecated immediately.
+## Install
 
-## Why a bare install resolves it
+```bash
+npm install @format.dev/cli --save-dev
+```
 
-npm creates a `latest` tag on a package’s first publish and will not remove it,
-so `latest` points at this placeholder until Format reaches general
-availability. That is why the deprecation warning is there.
+## Commands
 
-- Beta releases go out under the `beta` tag.
-- General availability is when `latest` moves to a real release.
+| Command               | What it does                                                         |
+| --------------------- | -------------------------------------------------------------------- |
+| `format dev`          | Start the Format Studio dev server                                   |
+| `format compile`      | Compile documents into standalone renderers                          |
+| `format new project`  | Creates a completely fresh Format setup. Recommended for fresh repos |
+| `format init`         | Boostraps Format into an existing repo                               |
+| `format new document` | Scaffolds a new document                                             |
+| `format update`       | Updates to the latest Format version                                 |
+| `format version`      | Prints the current Format version you're using                       |
 
-## Format
+## Documentation
 
-- https://format.dev
-- https://github.com/format-hq/format-js
+The [docs](https://format.dev/docs/cli/overview) for the CLI.
 
-Licensed under MIT. The full text ships beside this file.
+## The lockstep model
+
+All public Format packages release in lockstep. The `version` field in `format.config.json` pins which release your project uses, and `format update` is the most consistent way to move it up or down.
+
+Format doesn't use the peer dependency model to enforce the dependency between our packages. It's all driven from this CLI.
+
+## Config
+
+`format.config.json` is JSON. It holds your version and project settings. The `$schema` URL at `format.dev/schema/format-config.json` gives you editor autocomplete. [Docs](https://format.dev/docs/studio/configuration).

package/bin/format.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Committed launcher for the `format` bin. pnpm only creates a bin shim when
+// the target file exists at install time, and a fresh checkout (CI) installs
+// before dist/ is built — pointing `bin` straight at dist/index.mjs means no
+// shim is ever created there. This file always exists, so the shim always
+// links; it defers to the built CLI at run time.
+const distEntry = new URL('../dist/index.mjs', import.meta.url)
+
+try {
+	await import(distEntry.href)
+} catch (error) {
+	const isMissingDist = error?.code === 'ERR_MODULE_NOT_FOUND' && error.message.includes('dist/index.mjs')
+
+	if (!isMissingDist) {
+		throw error
+	}
+
+	console.error('@format.dev/cli is not built (dist/ is missing). Run `pnpm build` from the repo root, then re-run.')
+	process.exit(1)
+}

package/dist/config-Dq7O4e8N.mjs

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+
+//#region src/errors.ts
+var CliError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CliError";
+	}
+};
+
+//#endregion
+//#region src/config.ts
+const DEFAULT_CONFIG_BASE_NAME = "format.config";
+const CONFIG_EXTENSIONS = ["json", "jsonc"];
+function findConfigPath(startDir, options) {
+	const baseName = options?.baseName ?? DEFAULT_CONFIG_BASE_NAME;
+	const names = CONFIG_EXTENSIONS.map((extension) => `${baseName}.${extension}`);
+	let dir = resolve(startDir);
+	for (;;) {
+		for (const name of names) {
+			const candidate = join(dir, name);
+			if (existsSync(candidate)) return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+async function readConfigFile(filepath) {
+	const raw = await fs.readFile(filepath, "utf8");
+	const errors = [];
+	const config = parse(raw, errors, { allowTrailingComma: true });
+	if (errors.length > 0) throw new CliError(`Could not parse ${filepath}: ${errors.map((error) => {
+		const line = raw.slice(0, error.offset).split("\n").length;
+		return `${printParseErrorCode(error.error)} at line ${line}`;
+	}).join(", ")}`);
+	if (typeof config !== "object" || config === null || Array.isArray(config)) throw new CliError(`Invalid Format config in ${filepath}: expected a JSON object.`);
+	return {
+		filepath,
+		config,
+		raw
+	};
+}
+async function writeConfigVersion(args) {
+	const { filepath, version } = args;
+	const raw = await fs.readFile(filepath, "utf8");
+	const indent = detectIndent(raw);
+	const edits = modify(raw, ["version"], version, { formattingOptions: {
+		insertSpaces: !indent.includes("	"),
+		tabSize: indent.includes("	") ? 4 : indent.length
+	} });
+	await fs.writeFile(filepath, applyEdits(raw, edits), "utf8");
+}
+function detectIndent(raw) {
+	const match = raw.match(/^[ \t]+/m);
+	return match ? match[0] : "	";
+}
+
+//#endregion
+export { readConfigFile as a, findConfigPath as i, DEFAULT_CONFIG_BASE_NAME as n, writeConfigVersion as o, detectIndent as r, CliError as s, CONFIG_EXTENSIONS as t };

package/dist/config.d.mts

@@ -0,0 +1,21 @@
+//#region src/config.d.ts
+declare const DEFAULT_CONFIG_BASE_NAME = "format.config";
+declare const CONFIG_EXTENSIONS: string[];
+interface FormatConfigFile {
+  filepath: string;
+  config: Record<string, unknown>;
+  raw: string;
+}
+interface FindConfigPathOptions {
+  baseName?: string;
+}
+declare function findConfigPath(startDir: string, options?: FindConfigPathOptions): string | null;
+declare function readConfigFile(filepath: string): Promise<FormatConfigFile>;
+interface WriteConfigVersionArgs {
+  filepath: string;
+  version: string;
+}
+declare function writeConfigVersion(args: WriteConfigVersionArgs): Promise<void>;
+declare function detectIndent(raw: string): string;
+//#endregion
+export { CONFIG_EXTENSIONS, DEFAULT_CONFIG_BASE_NAME, FormatConfigFile, detectIndent, findConfigPath, readConfigFile, writeConfigVersion };

package/dist/config.mjs

@@ -0,0 +1,3 @@
+import { a as readConfigFile, i as findConfigPath, n as DEFAULT_CONFIG_BASE_NAME, o as writeConfigVersion, r as detectIndent, t as CONFIG_EXTENSIONS } from "./config-Dq7O4e8N.mjs";
+
+export { CONFIG_EXTENSIONS, DEFAULT_CONFIG_BASE_NAME, detectIndent, findConfigPath, readConfigFile, writeConfigVersion };

package/dist/draw-random-name-BzvSSVqO.d.mts

@@ -0,0 +1,4 @@
+//#region src/scaffold/document/draw-random-name.d.ts
+declare function drawRandomName(): string;
+//#endregion
+export { drawRandomName as t };

package/dist/draw-random-name-Dpt6YmUk.mjs

@@ -0,0 +1,13 @@
+import { animals, colors, uniqueNamesGenerator } from "unique-names-generator";
+
+//#region src/scaffold/document/draw-random-name.ts
+function drawRandomName() {
+	return uniqueNamesGenerator({
+		dictionaries: [colors, animals],
+		separator: "-",
+		style: "lowerCase"
+	});
+}
+
+//#endregion
+export { drawRandomName as t };

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };