@useguano/create 0.1.3 → 0.1.5

package/README.md

@@ -6,15 +6,24 @@ Scaffold a new [Guano](https://www.npmjs.com/package/@useguano/guano) site proje
 npm create @useguano
 ```
 
-Asks for a folder name (default `my-site`), creates it with `@useguano/guano`
-as a dependency plus `dev`/`start`/`build` scripts, a `.env.example` and a
-`.gitignore`, and runs `npm install`. Then:
+Asks for a folder name (default `my-site`), whether to connect **Claude
+Desktop** over MCP (default yes — quit Claude first), and the two agent
+permissions (may it edit the live project, may it publish — both default no).
+Then it creates the folder with `@useguano/guano` as a dependency plus
+`dev`/`start`/`build`/`connect` scripts, a `.env.example` and a `.gitignore`,
+runs `npm install`, and connects Claude. Then:
 
 ```sh
 cd my-site
 npm run dev
 ```
 
-Open `http://localhost:4174/admin` and create the first account. Pass the
-folder as an argument to skip the prompt (`npm create @useguano my-site`), and
-`--no-install` to skip the install step.
+Open `http://localhost:4174/admin` and create the first account — the Claude
+token is bound to it, and the form shows the permissions you chose. Change
+them any time in Settings → MCP → Agent permissions.
+
+Flags: pass the folder to skip that prompt (`npm create @useguano my-site`);
+`--no-install` skips the install; `--no-connect` skips Claude, `--connect`
+connects without asking, `--main` / `--publish` grant the permissions
+non-interactively. Without a terminal (CI) nothing is asked and Claude is not
+connected.

package/index.js

@@ -1,34 +1,118 @@
 #!/usr/bin/env node
-// @useguano/create: scaffold a project dir that runs Guano via npm scripts, then
-// install it. Zero dependencies — prompts with node:readline when no dir is
-// given. `npm create @useguano [dir] [--no-install]`.
+// @useguano/create: scaffold a project dir that runs Guano via npm scripts,
+// install it, and connect Claude Desktop — all in this one command, so what
+// is left afterwards is `cd my-site && npm run dev`. Zero dependencies —
+// prompts with node:readline.
+//
+//   npm create @useguano [dir] [--no-install] [--no-connect | --connect]
+//                        [--main] [--publish] [--config <claude config path>]
+//
+// The MCP connect runs through the just-installed package's own
+// `guano connect --offline`: it mints a PENDING API token into <dir>/data,
+// writes the two agent permissions there, and writes Claude Desktop's config.
+// The server binds the token to the first admin at /admin setup, and the
+// setup form shows the permissions instead of asking them again.
 import { spawnSync } from 'node:child_process'
+import { createServer } from 'node:net'
+import { existsSync } from 'node:fs'
 import { mkdir, readdir, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import readline from 'node:readline/promises'
 
 const args = process.argv.slice(2)
-const install = !args.includes('--no-install')
-let dir = args.find((a) => !a.startsWith('--'))
+const flag = (name) => args.includes(name)
+const opt = (name) => {
+  const i = args.indexOf(name)
+  return i !== -1 ? args[i + 1] : undefined
+}
+const install = !flag('--no-install')
+const interactive = process.stdin.isTTY && process.stdout.isTTY
+let dir = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--config')
 const DEFAULT_DIR = 'my-site'
+
+// ---- every question first, so a ^C anywhere here changes nothing ----
+const rl = interactive ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null
+const ask = (q) => rl.question(q)
+const yes = async (q, dflt) => {
+  const a = (await ask(`${q} [${dflt ? 'Y/n' : 'y/N'}] `)).trim()
+  return a ? /^y(es)?$/i.test(a) : dflt
+}
+
 if (!dir) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
-  dir = (await rl.question(`Project folder (${DEFAULT_DIR}): `)).trim() || DEFAULT_DIR
-  rl.close()
+  dir = rl ? (await ask(`Project folder (${DEFAULT_DIR}): `)).trim() || DEFAULT_DIR : DEFAULT_DIR
+}
+
+// Connect Claude Desktop? Flags decide non-interactively (CI never asks and
+// never connects); a terminal asks, default yes.
+let connect = false
+let policyFlags = []
+if (flag('--no-connect')) {
+  connect = false
+} else if (flag('--connect') || flag('--main') || flag('--publish')) {
+  connect = true
+} else if (rl) {
+  connect = await yes('Connect Claude Desktop to this site over MCP?', true)
+}
+if (connect) {
+  if (flag('--main')) policyFlags.push('--main')
+  if (flag('--publish')) policyFlags.push('--publish')
+  if (!policyFlags.length && rl && !flag('--connect')) {
+    console.log('\nTwo questions about what the agent may do (change them any time in\n/admin → Settings → MCP → Agent permissions):\n')
+    if (await yes('Let agents edit the live project (Main)? Off, they work in a draft you apply yourself.', false))
+      policyFlags.push('--main')
+    if (await yes('Let agents publish the site? Off, they can still preview their work.', false))
+      policyFlags.push('--publish')
+    console.log('')
+  }
 }
 
 const target = resolve(dir)
-const name = basename(target)
-  .toLowerCase()
-  .replace(/[^a-z0-9-]+/g, '-')
-  .replace(/^-+|-+$/g, '') || DEFAULT_DIR
+const name =
+  basename(target)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || DEFAULT_DIR
 
 await mkdir(target, { recursive: true })
 if ((await readdir(target)).length) {
+  rl?.close()
   console.error(`${target} is not empty — refusing to scaffold over existing files`)
   process.exit(1)
 }
 
+/**
+ * A free port for THIS project, written into .env as an explicit PORT.
+ *
+ * Every project used to default to 4174, so a second one on the same machine
+ * lost the race and walked to the next free port — which left its MCP entry,
+ * the Vite proxy and any open tab addressing the FIRST project's socket, where
+ * its own token is unknown and the 401 reads as "the token is dead". An
+ * explicit port is a contract the server honours instead of walking, and
+ * putting it in a file the user can read makes "which port is this site on" a
+ * question with an answer.
+ *
+ * 4174 is still preferred, so a first project looks exactly as documented.
+ */
+async function pickPort(first = 4174, tries = 40) {
+  // A site needs its own port AND the preview port above it, so step by two.
+  for (let port = first; port < first + tries * 2; port += 2) {
+    if ((await free(port)) && (await free(port + 1))) return port
+  }
+  return first
+}
+
+function free(port) {
+  return new Promise((resolve) => {
+    const probe = createServer()
+    probe.once('error', () => resolve(false))
+    probe.once('listening', () => probe.close(() => resolve(true)))
+    probe.listen(port, '0.0.0.0')
+  })
+}
+
+const port = await pickPort()
+
 const files = {
   'package.json':
     JSON.stringify(
@@ -56,7 +140,16 @@ const files = {
 export default {}
 `,
 
-  '.env.example': `# PORT=4174
+  // A real .env, not just the example: the port is this project's identity on
+  // the machine, and leaving it to the 4174 default is what makes two projects
+  // fight over one address.
+  '.env': `# This project's own port. Keep it — two Guano sites on one machine
+# must not share one, or whichever starts first answers for both and the
+# other's MCP token is refused with a 401.
+PORT=${port}
+`,
+
+  '.env.example': `PORT=${port}
 # GUANO_DATA_DIR=./data     # users, media, drafts, the published site — back this up
 # COOKIE_SECURE=1           # set 0 only for plain-HTTP LAN setups
 # PUBLISH_TOKEN=            # optional: token for CI publishes
@@ -77,12 +170,20 @@ A [Guano](https://www.npmjs.com/package/@useguano/guano) site.
 npm run dev
 \`\`\`
 
-Open http://localhost:4174/admin, create the first account, build your site.
-Your published site is served at http://localhost:4174/.
+Open http://localhost:${port}/admin, create the first account, then build your
+site. Your published site is served at http://localhost:${port}/.
+
+This project runs on port ${port} (set in \`.env\`). Each Guano site on a
+machine needs its own, so two of them never answer for one address.
+
+If you said yes to Claude Desktop when scaffolding, it is already connected:
+the agent token is bound to the admin account you create, and the permissions
+you chose (edit the live project, publish) show on the setup form and stay
+editable in Settings → MCP → Agent permissions.
 
 - \`npm run start\` — production server (\`NODE_ENV=production\`)
 - \`npm run build\` — export the site as static files to \`./dist-site\`
-- \`npm run connect\` — connect Claude Desktop to this instance over MCP (quit Claude first)
+- \`npm run connect\` — connect Claude Desktop later, or from another machine (quit Claude first; \`--main\` / \`--publish\` grant the agent permissions, or it asks)
 - everything lives in \`./data\` — **backing up = copying that directory**
 
 See the @useguano/guano package README for deploy notes and environment variables.
@@ -104,8 +205,45 @@ if (install) {
   if (!installed) console.error('\nnpm install failed — run it yourself in the project folder.')
 }
 
+// ---- connect Claude Desktop, through the installed package ----
+// GUANO_CREATE_LOCAL_PKG is a dev-only escape hatch: with --no-install there
+// is no node_modules, so a repo checkout names its own packages/guano here.
+let connected = false
+if (connect) {
+  const pkgDir = existsSync(join(target, 'node_modules', '@useguano', 'guano'))
+    ? join(target, 'node_modules', '@useguano', 'guano')
+    : process.env.GUANO_CREATE_LOCAL_PKG
+  if (!pkgDir) {
+    console.error('\nClaude Desktop not connected: guano is not installed yet — run `npm run connect` inside the project later.')
+  } else {
+    try {
+      // the package resolves its data dir from this env at import time
+      const dataDir = join(target, 'data')
+      await mkdir(dataDir, { recursive: true, mode: 0o700 })
+      process.env.GUANO_DATA_DIR = dataDir
+      const { main } = await import(pathToFileURL(join(pkgDir, 'mcp', 'connect.mjs')).href)
+      const connectArgs = [...policyFlags, '--offline', '--yes']
+      if (opt('--config')) connectArgs.push('--config', resolve(opt('--config')))
+      console.log('\nConnecting Claude Desktop…')
+      await main(connectArgs, {
+        whenClaudeRunning: async () => {
+          if (!rl) return 'skip'
+          const a = (
+            await ask('Claude Desktop is running and overwrites its config on quit. Quit it, then press Enter (or type skip): ')
+          ).trim()
+          return /^s(kip)?$/i.test(a) ? 'skip' : 'retry'
+        },
+      })
+      connected = true
+    } catch (e) {
+      console.error(`\n✗ ${e?.message ?? e}\n  Claude Desktop not connected — run \`npm run connect\` inside the project later.`)
+    }
+  }
+}
+rl?.close()
+
 console.log(`
 Next:
-  cd ${dir}${installed ? '' : '\n  npm install'}
-  npm run dev   → http://localhost:4174/admin
-`)
+  cd ${dir}${installed || !install ? '' : '\n  npm install'}
+  npm run dev   → http://localhost:4174/admin  (create your admin account)
+${connected ? '\nThen open Claude Desktop — guano is connected; the agent token is bound to the admin you create.\n' : ''}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useguano/create",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "AGPL-3.0-only",
   "publishConfig": {
     "access": "public"