paneltir 0.6.0

package/bin/paneltir.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * The kit's command line: `paneltir init`, `paneltir version`, `paneltir check`.
+ *
+ * The panel is two halves that install differently. The components are a
+ * library, so they arrive in node_modules and are never edited. The gate — the
+ * password, the session, the write-back to GitHub — is not: it holds this
+ * project's password, points at this project's repository, and runs on the
+ * hosting platform rather than in the bundle. Shipping it inside the library
+ * would mean every project's front door moving when the library updates, which
+ * is the opposite of what a front door is for.
+ *
+ * So `init` copies those files into the project once. From then on they belong
+ * to the project: readable, editable, in its own git history. Re-running never
+ * overwrites what is already there.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(here, '..')
+const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
+
+let fingerprint = { hash: 'unknown', fileCount: 0 }
+try {
+  fingerprint = JSON.parse(readFileSync(join(packageRoot, 'fingerprint.json'), 'utf8'))
+} catch {
+  /* installed without it; version alone is still useful */
+}
+
+const shortHash = fingerprint.hash.replace('sha256:', '').slice(0, 12)
+
+/** Every file under a directory, as paths relative to it. */
+function walk(dir, base = dir) {
+  const out = []
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) out.push(...walk(full, base))
+    else out.push(relative(base, full))
+  }
+  return out
+}
+
+/**
+ * What this project already has.
+ *
+ * A project installing this is rarely empty: it usually has a dashboard, a
+ * palette, and often a password already in use. Asking it to invent all three
+ * again is how a migration produces a second admin area nobody retires and a
+ * second password nobody remembers. So look first, and say what was found.
+ *
+ * Nothing here reads a secret's value — only whether a name appears — and
+ * nothing is written from what is found.
+ */
+function survey(target) {
+  const found = { password: [], panels: [], palettes: [], kits: [] }
+
+  const readIf = (file) => {
+    try {
+      return readFileSync(join(target, file), 'utf8')
+    } catch {
+      return null
+    }
+  }
+
+  // A password already in use, under whatever name this project gave it.
+  const PASSWORD_NAMES = /^\s*(?:export\s+)?([A-Z0-9_]*(?:ADMIN|PANEL|DASHBOARD|BOARD)[A-Z0-9_]*(?:PASSWORD|PASS|SECRET|TOKEN)[A-Z0-9_]*)\s*=/gm
+  for (const file of ['.env', '.env.local', '.env.production', '.env.example', '.env.development']) {
+    const body = readIf(file)
+    if (!body) continue
+    for (const match of body.matchAll(PASSWORD_NAMES)) {
+      found.password.push({ file, name: match[1] })
+    }
+  }
+
+  // An admin area already built.
+  for (const dir of ['src/admin', 'src/dashboard', 'app/admin', 'app/dashboard', 'pages/admin', 'src/pages/admin', 'admin']) {
+    try {
+      if (statSync(join(target, dir)).isDirectory()) found.panels.push(dir)
+    } catch {
+      /* not there */
+    }
+  }
+
+  // A palette already chosen — the thing to adopt before drawing anything.
+  for (const file of [
+    'tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.cjs',
+    'src/theme.ts', 'src/theme.tsx', 'src/styles/theme.css', 'src/theme/index.ts',
+    'src/styles/tokens.css', 'src/index.css', 'src/App.css', 'styles/globals.css',
+  ]) {
+    if (readIf(file) !== null) found.palettes.push(file)
+  }
+
+  // Another dashboard kit still installed.
+  const pkgJson = readIf('package.json')
+  if (pkgJson) {
+    try {
+      const deps = { ...JSON.parse(pkgJson).dependencies, ...JSON.parse(pkgJson).devDependencies }
+      for (const name of Object.keys(deps || {})) {
+        if (/(dashboard|admin|tremor|refine|react-admin)/i.test(name) && name !== 'paneltir') {
+          found.kits.push(name)
+        }
+      }
+    } catch {
+      /* unreadable package.json is not this command's problem */
+    }
+  }
+
+  return found
+}
+
+function reportSurvey(found) {
+  const lines = []
+
+  if (found.palettes.length) {
+    lines.push(`This project already has a palette. Adopt it before drawing anything:
+  ${found.palettes.slice(0, 4).join('\n  ')}
+Map those colours onto DashboardThemeTokens rather than inventing new ones —
+a dashboard in colours nobody chose is the first thing people ask to change.`)
+  } else {
+    lines.push(`No palette found. Do not invent one: the kit ships midnight, oldMoney and
+cyberpunk as starting points, and INSTALL.md says how to pick.`)
+  }
+
+  if (found.password.length) {
+    const names = [...new Set(found.password.map((p) => p.name))]
+    lines.push(`This project already has a password: ${names.join(', ')}
+  (in ${[...new Set(found.password.map((p) => p.file))].join(', ')})
+Reuse it. Either rename it to ADMIN_PASSWORD, or edit lib/session.ts to read
+the name you already use. Do not add a second password — two passwords for one
+admin area is one password nobody can remember and one nobody rotates.`)
+  }
+
+  if (found.panels.length) {
+    lines.push(`There is already an admin area here: ${found.panels.join(', ')}
+Build the new board inside it rather than beside it, and delete what it
+replaces in the same change. An old panel left running is one still reachable.`)
+  }
+
+  if (found.kits.length) {
+    lines.push(`Another dashboard package is still installed: ${found.kits.join(', ')}
+Remove it once the board is moved over, or the project ships both.`)
+  }
+
+  return lines
+}
+
+/** The board. Never replaced once it exists — see the loop below. */
+const BOARD_SEED = 'src/data/panel-state.json'
+
+function init(args) {
+  const force = args.includes('--force')
+  const target = process.cwd()
+  const templateDir = join(packageRoot, 'template')
+
+  if (!existsSync(templateDir)) {
+    console.error('paneltir: this install has no template/ directory.')
+    process.exit(1)
+  }
+
+  const files = walk(templateDir).sort()
+  const written = []
+  const kept = []
+
+  for (const file of files) {
+    const from = join(templateDir, file)
+    const to = join(target, file)
+    // --force replaces the gate, which is code and can be re-copied. It never
+    // touches the board: that file stops being a template the moment the
+    // project writes its first card into it, and overwriting somebody's board
+    // because they asked to refresh their middleware is unforgivable.
+    const protectedFile = file === BOARD_SEED
+    if (existsSync(to) && (!force || protectedFile)) {
+      kept.push(file)
+      continue
+    }
+    mkdirSync(dirname(to), { recursive: true })
+    cpSync(from, to)
+    written.push(file)
+  }
+
+  console.log(`paneltir ${pkg.version} — the panel's gate, into ${target}\n`)
+
+  const notes = reportSurvey(survey(target))
+  if (notes.length) {
+    console.log('What this project already has\n')
+    for (const note of notes) console.log(`  ${note.replace(/\n/g, '\n  ')}\n`)
+  }
+
+  if (written.length) {
+    console.log('Written:')
+    for (const file of written) console.log(`  + ${file}`)
+  }
+  if (kept.length) {
+    console.log(`${written.length ? '\n' : ''}Left alone (already yours${force ? '' : '; --force to replace'}):`)
+    for (const file of kept) console.log(`  = ${file}`)
+  }
+
+  if (!written.length) {
+    console.log('\nNothing to do — every file is already in place.')
+    return
+  }
+
+  console.log(`
+These files are yours now. They are not part of the library and will not
+change when it updates: read them, edit them, commit them.
+
+  src/data/panel-state.json          your board. Empty, with the columns and
+                                     three questions nobody has answered yet.
+                                     \`init --force\` never overwrites it.
+  .claude/skills/panel/SKILL.md      how Claude reads and writes that board:
+                                     what an order means, which taps are
+                                     refusals, and what moving a card claims.
+                                     Say \`/panel\` in a session to use it.
+
+Set these where the project is hosted, never in the repository:
+
+  ADMIN_PASSWORD   the panel password. Required — without it the panel
+                   answers 503 rather than becoming public.
+  GH_TOKEN         a fine-grained token with contents: read and write on
+                   THIS project's repository only.
+  PANEL_REPO       this project's "owner/repo".
+  PANEL_FILE       where the board lives in it, if not src/data/panel-state.json.
+  SESSION_SECRET   optional. Defaults to ADMIN_PASSWORD, so changing the
+                   password ends every session already issued.
+
+Then check two things before trusting it:
+
+  1. Opening /admin signed out lands on /login, not on the panel.
+  2. The panel's own JavaScript bundle answers 401 signed out. If it does
+     not, adjust the last entry of the matcher in middleware.ts to wherever
+     this project's build emits it — protecting the page but not the bundle
+     leaves the board readable by anyone who opens the HTML.
+`)
+}
+
+function version() {
+  console.log(`paneltir v${pkg.version}`)
+  console.log(`fingerprint ${fingerprint.hash}`)
+  console.log(`${fingerprint.fileCount} tracked files`)
+  console.log(`installed from github:daifukus/paneltir#v${pkg.version}`)
+}
+
+/**
+ * Answers "is this project on the version it thinks it is?" without anyone
+ * reading node_modules — the question every dashboard needs to answer before
+ * a bug report is worth anything.
+ */
+function check(args) {
+  const expected = args.find((a) => !a.startsWith('-'))
+  if (!expected) {
+    console.log(`paneltir v${pkg.version} · ${shortHash}`)
+    console.log(`\nPass a version to compare against, e.g. paneltir check ${pkg.version}`)
+    return
+  }
+  const want = expected.replace(/^v/, '')
+  if (want === pkg.version) {
+    console.log(`ok — paneltir v${pkg.version} · ${shortHash}`)
+    return
+  }
+  console.error(`paneltir is v${pkg.version}, expected v${want}`)
+  console.error(`\nInstall the one you meant:\n  npm install github:daifukus/paneltir#v${want}`)
+  process.exit(1)
+}
+
+/**
+ * Reads this project's board and says what is wrong with it.
+ *
+ * The panel refuses to save a broken board and CI refuses to ship one, but
+ * neither helps the person who has just edited the file by hand and wants to
+ * know before they push. This is that answer, from the same check.
+ */
+function board(args) {
+  const file = args.find((a) => !a.startsWith('-')) || process.env.PANEL_FILE || 'src/data/panel-state.json'
+  const path = resolve(process.cwd(), file)
+
+  if (!existsSync(path)) {
+    console.error(`no board at ${file}`)
+    console.error('\nPass its path, or run `paneltir init` to write an empty one.')
+    process.exit(1)
+  }
+
+  const check = readBoard(readFileSync(path, 'utf8'))
+  if (check.ok) {
+    const cards = check.board.cards.length
+    console.log(`ok  ${file} — ${cards} card${cards === 1 ? '' : 's'}, ${check.board.columns.length} columns`)
+    return
+  }
+
+  console.error(`${file} cannot be read as a board:\n`)
+  for (const problem of check.problems) {
+    console.error(problem.at ? `  ${problem.at}\n    ${problem.says}` : `  ${problem.says}`)
+  }
+  if (check.reason === 'version') {
+    console.error(`\nThis is not damage: the board is written for another version of the kit.`)
+  } else {
+    console.error(`\nThe file is in git. \`git diff ${file}\` shows what changed.`)
+  }
+  process.exit(1)
+}
+
+const { readBoard } = await import(pathToFileURL(join(here, '../dist/index.js')).href)
+
+const [command, ...rest] = process.argv.slice(2)
+
+switch (command) {
+  case 'init':
+    init(rest)
+    break
+  case 'version':
+    version()
+    break
+  case 'check':
+    check(rest)
+    break
+  case 'board':
+    board(rest)
+    break
+  default:
+    console.log(`paneltir v${pkg.version} · ${shortHash}
+
+  paneltir init [--force]   copy the panel's gate into this project
+  paneltir version          what is installed, and where it came from
+  paneltir check [version]  fail if the installed version is not the one meant
+  paneltir board [file]     read this project's board and say what is wrong
+
+The components install as a library and are never edited. The gate — password,
+session, write-back — is copied in by init and belongs to the project.`)
+    if (command) process.exit(1)
+}