@ham2k/extension-tools 0.2.0 → 0.4.0

package/h2kext-init.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // Scaffolds an extension project (HALO-452, docs/extensions/distribution.md).
 //
@@ -16,17 +16,17 @@
 // `n0call-my-extension` VALIDATES — N0CALL is a well-formed callsign — so it
 // would ship, which is the one outcome the naming convention exists to stop.
 
-import { readFileSync } from 'node:fs'
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { readFileSync } from "node:fs"
+import { access, mkdir, readFile, writeFile } from "node:fs/promises"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
 
-import { EXAMPLE_BUILD_SCRIPT } from './h2kext-build.mjs'
-import { H2KEXT_API_VERSION, SCAFFOLD_SHARED_DEPENDENCIES, keyProblem } from './h2kext.mjs'
+import { EXAMPLE_BUILD_SCRIPT } from "./h2kext-build.mjs"
+import { H2KEXT_API_VERSION, SCAFFOLD_SHARED_DEPENDENCIES, keyProblem } from "./h2kext.mjs"
 
 const args = process.argv.slice(2)
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   console.log(`Scaffold a Ham2K Logger extension.
 
   h2kext-init <key> [--dir <path>] [--name "<display name>"]
@@ -35,10 +35,11 @@ The key is '<yourcallsign>-<name>' — e.g. ki2d-my-clock. The callsign is a
 namespace you already have, globally unique, so two authors who never met
 cannot collide. It also namespaces your extension's storage.
 
-Writes manifest.json, src/index.ts, build.mjs, tsconfig.json, AGENTS.md and
-.gitignore into <path> (default: the working directory), refusing rather than
-overwrite anything already there. An existing package.json is added to — the
-scripts and dependencies this needs, nothing of yours replaced.`)
+Writes manifest.json, src/index.ts, build.mjs, tsconfig.json, AGENTS.md,
+.prettierrc.json and .gitignore into <path> (default: the working directory),
+refusing rather than overwrite anything already there. An existing
+package.json is added to — the scripts and dependencies this needs, nothing of
+yours replaced.`)
   process.exit(args.length === 0 ? 1 : 0)
 }
 
@@ -48,9 +49,9 @@ let displayName
 for (let i = 0; i < args.length; i++) {
   // `resolve('')` is the working directory, so a bare `--dir` would scaffold
   // wherever the author happened to be standing.
-  if (args[i] === '--dir') dir = args[++i] ? resolve(args[i]) : undefined
-  else if (args[i] === '--name') displayName = args[++i]
-  else if (!args[i].startsWith('-') && key === undefined) key = args[i]
+  if (args[i] === "--dir") dir = args[++i] ? resolve(args[i]) : undefined
+  else if (args[i] === "--name") displayName = args[++i]
+  else if (!args[i].startsWith("-") && key === undefined) key = args[i]
 }
 
 const problem = keyProblem(key)
@@ -60,16 +61,21 @@ if (problem) {
 }
 
 if (dir === undefined) {
-  console.error('h2kext-init: --dir needs the directory to scaffold into')
+  console.error("h2kext-init: --dir needs the directory to scaffold into")
   process.exit(1)
 }
 
-const shortKey = key.slice(key.indexOf('-') + 1)
-const name = displayName ??
-  shortKey.split('-').filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ')
+const shortKey = key.slice(key.indexOf("-") + 1)
+const name =
+  displayName ??
+  shortKey
+    .split("-")
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(" ")
 
 const here = dirname(fileURLToPath(import.meta.url))
-const { version: toolsVersion } = JSON.parse(await readFile(join(here, 'package.json'), 'utf8'))
+const { version: toolsVersion } = JSON.parse(await readFile(join(here, "package.json"), "utf8"))
 
 /// The SDK is a SEPARATE package on its own version line, so this cannot be
 /// answered with the version of the tools that happen to be running: a
@@ -93,8 +99,8 @@ function sdkRange(projectDir) {
   for (const start of [projectDir, here]) {
     for (let dir = start; ; dir = dirname(dir)) {
       try {
-        const path = join(dir, 'node_modules/@ham2k/extension-sdk/package.json')
-        const { version } = JSON.parse(readFileSync(path, 'utf8'))
+        const path = join(dir, "node_modules/@ham2k/extension-sdk/package.json")
+        const { version } = JSON.parse(readFileSync(path, "utf8"))
         if (version) return `^${version}`
       } catch {
         // Not here; walk up to the next node_modules.
@@ -102,63 +108,91 @@ function sdkRange(projectDir) {
       if (dirname(dir) === dir) break
     }
   }
-  return 'latest'
+  return "latest"
+}
+
+/// One object of a JSON file, indented as Prettier indents it. Prettier keeps
+/// an object expanded when it was written expanded, so nesting one of these
+/// inside a template is stable at any width; an ARRAY it re-decides by width,
+/// which is why every array below is written inline by hand rather than
+/// stringified. Held by a test that formats everything the scaffold writes
+/// and compares it with what Prettier would have produced.
+function nestedJson(value, indent) {
+  return JSON.stringify(value, null, 2).replaceAll("\n", `\n${indent}`)
 }
 
 /// What the project's package.json has to say for the build, the packer and
 /// the typecheck to run.
 const projectPackage = {
   name: key,
-  version: '0.1.0',
+  version: "0.1.0",
   private: true,
-  type: 'module',
+  type: "module",
   scripts: {
-    build: 'node build.mjs',
-    pack: 'h2kext-pack build',
-    typecheck: 'tsc --noEmit',
+    build: "node build.mjs",
+    pack: "h2kext-pack build",
+    typecheck: "tsc --noEmit",
+    format: "prettier --write .",
+    "format:check": "prettier --check .",
   },
   dependencies: {
-    '@ham2k/extension-sdk': sdkRange(dir),
+    "@ham2k/extension-sdk": sdkRange(dir),
   },
   devDependencies: {
-    '@ham2k/extension-tools': `^${toolsVersion}`,
-    esbuild: '^0.25.0',
-    typescript: '^5.6.0',
+    "@ham2k/extension-tools": `^${toolsVersion}`,
+    esbuild: "^0.25.0",
+    // A patch range, not a caret: Prettier changes its output in a MINOR, and
+    // the templates below are checked against one version here. A caret would
+    // let an author install a 3.x that formats differently and fail the first
+    // `format:check` on files they never touched.
+    prettier: "~3.9.0",
+    typescript: "^5.6.0",
   },
 }
 
 const files = {
-  'manifest.json': `${JSON.stringify({
-    key,
-    name,
-    version: '0.1.0',
-    description: `${name}, an extension for the Ham2K Logger`,
-    category: 'dashboard',
-    api: H2KEXT_API_VERSION,
-    icon: 'hand-wave-outline',
-    // The Extensions list reads this without evaluating any bundle, and the
-    // Add-Panel route shows only what declares `panel`. Undeclared, a panel
-    // extension installs and then cannot be found or switched on.
-    hooks: ['panel'],
-    sharedDependencies: SCAFFOLD_SHARED_DEPENDENCIES,
-  }, null, 2)}\n`,
-
-  'build.mjs': EXAMPLE_BUILD_SCRIPT,
-
-  'src/index.ts': `// ${name} — a panel that says hello.
+  // `hooks` is what the Extensions list reads without evaluating any bundle,
+  // and the Add-Panel route shows only what declares `panel`. Undeclared, a
+  // panel extension installs and then cannot be found or switched on.
+  "manifest.json": `{
+  "key": ${JSON.stringify(key)},
+  "name": ${JSON.stringify(name)},
+  "version": "0.1.0",
+  "description": ${JSON.stringify(`${name}, an extension for the Ham2K Logger`)},
+  "category": "dashboard",
+  "api": ${JSON.stringify(H2KEXT_API_VERSION)},
+  "icon": "hand-wave-outline",
+  "hooks": ["panel"],
+  "sharedDependencies": ${nestedJson(SCAFFOLD_SHARED_DEPENDENCIES, "  ")}
+}
+`,
+
+  "build.mjs": EXAMPLE_BUILD_SCRIPT,
+
+  "src/index.ts": `// ${name} — a panel that says hello.
 //
 // Everything here is the minimum: one hook, one descriptor, one render. See
 // node_modules/@ham2k/extension-sdk/AGENTS.md for what to read next.
 
-import { defineExtension } from '@ham2k/extension-sdk'
-import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from '@ham2k/extension-sdk'
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from "@ham2k/extension-sdk"
 
-import manifest from '../manifest.json'
+import manifest from "../manifest.json"
 
 const HelloPanel: PanelHook = {
   /// What the operator sees when choosing a panel to place.
   async getPanels(_args: Record<string, never>, _ctx: HookContext): Promise<PanelDescriptor[]> {
-    return [{ key: 'hello', title: ${JSON.stringify(name)}, description: 'A panel that says hello', icon: 'hand-wave-outline' }]
+    // Written a field per line, and left that way by the formatter: on one
+    // line a long enough --name would push it past the width and the
+    // scaffold's own \`format:check\` would fail on untouched code.
+    return [
+      {
+        key: "hello",
+        title: ${JSON.stringify(name)},
+        description: "A panel that says hello",
+        icon: "hand-wave-outline",
+      },
+    ]
   },
 
   /// What the pane shows. A panel returns CONTENT, never widgets — which is
@@ -168,37 +202,38 @@ const HelloPanel: PanelHook = {
   /// its registered key and then calls this by name, so a near-miss is a panel
   /// that installs, activates, and then renders nothing.
   async render(_args: PanelRenderArgs, _ctx: HookContext): Promise<PanelContent> {
-    return { kind: 'markdown', content: '# Hello, World!' }
+    return { kind: "markdown", content: "# Hello, World!" }
   },
 }
 
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: '${key}', hook: HelloPanel })
+    registerHook("panel", { key: "${key}", hook: HelloPanel })
   },
 })
 `,
 
-  'tsconfig.json': `${JSON.stringify({
-    compilerOptions: {
-      target: 'ES2020',
-      module: 'ESNext',
-      moduleResolution: 'bundler',
-      lib: ['ES2020'],
-      strict: true,
-      noEmit: true,
-      skipLibCheck: true,
-      resolveJsonModule: true,
-    },
-    include: ['src/**/*.ts'],
-  }, null, 2)}\n`,
+  "tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"]
+}
+`,
 
   // The whole point of the file. Claude Code and its siblings read a project's
   // AGENTS.md before they touch anything, so this is what carries the hook
   // reference, the sandbox's limits and the manifest's shape into the session
   // — none of which anyone would think to go looking for in node_modules.
-  'AGENTS.md': `# ${name}
+  "AGENTS.md": `# ${name}
 
 An extension for the Ham2K Logger. How to write one, what the hooks are, and
 what the sandbox will and will not let you do:
@@ -206,14 +241,24 @@ what the sandbox will and will not let you do:
 @node_modules/@ham2k/extension-sdk/AGENTS.md
 `,
 
-  '.gitignore': 'node_modules/\nbuild/\n*.h2kext\n',
+  // The style the scaffolded files are already in, so `npm run format:check`
+  // passes on an untouched project. Prettier reads the project's .gitignore
+  // from its working directory, so build/ and the packed .h2kext are already
+  // out of its way and no .prettierignore is needed.
+  ".prettierrc.json": `{
+  "printWidth": 160,
+  "semi": false
+}
+`,
+
+  ".gitignore": "node_modules/\nbuild/\n*.h2kext\n",
 }
 
 // Reported together rather than one per run: a scaffold that stops at the
 // first collision has already written half a project, and the second attempt
 // then collides with its own output.
-const packagePath = join(dir, 'package.json')
-const currentPackage = await readFile(packagePath, 'utf8').then(
+const packagePath = join(dir, "package.json")
+const currentPackage = await readFile(packagePath, "utf8").then(
   (text) => {
     try {
       return JSON.parse(text)
@@ -225,27 +270,71 @@ const currentPackage = await readFile(packagePath, 'utf8').then(
       process.exit(1)
     }
   },
-  () => ({}))
+  () => ({}),
+)
 
 // `null`, `[]` and `"text"` all parse, and none of them is something to merge
 // into — reached at the end, each is a raw TypeError over six written files.
-if (currentPackage === null || typeof currentPackage !== 'object' || Array.isArray(currentPackage)) {
+if (currentPackage === null || typeof currentPackage !== "object" || Array.isArray(currentPackage)) {
   console.error(`h2kext-init: ${packagePath} is not a package description — nothing written`)
   process.exit(1)
 }
 
+// Prettier reads the FIRST config it finds, and a `prettier` key in the
+// package.json already here outranks a `.prettierrc.json` sitting beside it —
+// so writing ours would leave a file that is never read, under templates
+// formatted to a style the author's own config contradicts. Their config
+// wins; this one is dropped, and said out loud, because the alternative is a
+// project whose first `npm run format` rewrites every scaffolded file.
+const PRETTIER_CONFIG_FILES = [
+  ".prettierrc",
+  ".prettierrc.json",
+  ".prettierrc.json5",
+  ".prettierrc.yaml",
+  ".prettierrc.yml",
+  ".prettierrc.js",
+  ".prettierrc.mjs",
+  ".prettierrc.cjs",
+  ".prettierrc.toml",
+  "prettier.config.js",
+  "prettier.config.mjs",
+  "prettier.config.cjs",
+]
+const foundAt = async (path) =>
+  await access(join(dir, path)).then(
+    () => true,
+    () => false,
+  )
+let foreignPrettierConfig
+if (currentPackage.prettier !== undefined) foreignPrettierConfig = "the `prettier` key in package.json"
+else
+  for (const path of PRETTIER_CONFIG_FILES) {
+    if (path !== ".prettierrc.json" && (await foundAt(path))) {
+      foreignPrettierConfig = path
+      break
+    }
+  }
+if (foreignPrettierConfig) delete files[".prettierrc.json"]
+
 // `access`, not a read: a directory where a file should go, or one this
 // process cannot read, is something in the way — treated as absent, it becomes
 // a write loop that fails half-way through.
 const existing = []
 for (const path of Object.keys(files)) {
-  if (await access(join(dir, path)).then(() => true, () => false)) existing.push(path)
+  if (
+    await access(join(dir, path)).then(
+      () => true,
+      () => false,
+    )
+  )
+    existing.push(path)
 }
 if (existing.length) {
   const where = relative(process.cwd(), dir)
   console.error(
-    `h2kext-init: ${where.startsWith('..') ? dir : where || '.'} already holds ${existing.join(', ')} — ` +
-    'nothing written. Scaffold into an empty directory with --dir.')
+    `h2kext-init: ${where.startsWith("..") ? dir : where || "."} already holds ${existing.join(", ")} — ` +
+      "nothing written. Scaffold into an empty directory with --dir.",
+  )
   process.exit(1)
 }
 
@@ -262,15 +351,24 @@ for (const [path, content] of Object.entries(files)) {
 // Filled in key by key, never overwritten: what the author already declared —
 // their own name for the project, a version of esbuild they chose — is theirs.
 for (const [field, value] of Object.entries(projectPackage)) {
-  if (typeof value !== 'object') currentPackage[field] ??= value
+  if (typeof value !== "object") currentPackage[field] ??= value
   else for (const [name, entry] of Object.entries(value)) (currentPackage[field] ??= {})[name] ??= entry
 }
 await writeFile(packagePath, `${JSON.stringify(currentPackage, null, 2)}\n`)
 
 console.log(`${key} — ${name}
 
-  ${[...Object.keys(files), 'package.json'].join('\n  ')}
-
+  ${[...Object.keys(files), "package.json"].join("\n  ")}
+${
+  foreignPrettierConfig
+    ? `
+No .prettierrc.json written — ${foreignPrettierConfig} already configures
+Prettier here, and it is the one Prettier reads. The scaffolded files are in
+the style this command's own config describes (print width 160, no
+semicolons); \`npm run format\` will restyle them to yours.
+`
+    : ""
+}
 Next:
   npm install
   npm run build && npm run pack`)

package/h2kext-pack.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // Packages an extension into a `.h2kext` a user can install
 // (HALO-422, docs/extensions/distribution.md).
@@ -10,11 +10,11 @@
 // The directory holds a built `index.js`, a `manifest.json`, and optionally an
 // `assets/` folder. Nothing here compiles anything — see h2kext.mjs.
 
-import { pack, PackError, H2KEXT_API_VERSION, RESERVED_PREFIX } from './h2kext.mjs'
+import { pack, PackError, H2KEXT_API_VERSION, RESERVED_PREFIX } from "./h2kext.mjs"
 
 const args = process.argv.slice(2)
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   console.log(`Package an extension directory into a .h2kext bundle.
 
   h2kext-pack <directory> [-o <out.h2kext>] [--force-name]
@@ -37,19 +37,19 @@ Defaults to <key>-<version>.h2kext in the working directory.`)
 
 // Walked by index rather than matched by value: `args.indexOf(a)` finds the
 // FIRST occurrence, so `-o foo foo` mistook the output path for the directory.
-const forceName = args.includes('--force-name')
+const forceName = args.includes("--force-name")
 let dir
 let outPath
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '-o') {
+  if (args[i] === "-o") {
     outPath = args[++i]
-  } else if (!args[i].startsWith('-') && dir === undefined) {
+  } else if (!args[i].startsWith("-") && dir === undefined) {
     dir = args[i]
   }
 }
 
 if (!dir) {
-  console.error('h2kext-pack: name the directory to package')
+  console.error("h2kext-pack: name the directory to package")
   process.exit(1)
 }
 
@@ -58,11 +58,11 @@ try {
   const assets = result.files.length - 2
   console.log(`${result.outPath}`)
   console.log(`  ${result.manifest.key} ${result.manifest.version} — ${result.manifest.name}`)
-  console.log(`  ${assets} asset${assets === 1 ? '' : 's'}`)
+  console.log(`  ${assets} asset${assets === 1 ? "" : "s"}`)
   if (result.manifest.domains?.length) {
     // Named on the way out, because this is the one part of the manifest the
     // person installing it will be asked to approve.
-    console.log(`  may reach: ${result.manifest.domains.join(', ')}`)
+    console.log(`  may reach: ${result.manifest.domains.join(", ")}`)
   }
 } catch (e) {
   if (e instanceof PackError) {