agentbox-app 0.1.6

package/main/first-run.mjs

@@ -0,0 +1,190 @@
+// THE FIRST TASK'S ANSWER, READ OFF THE DISK.
+//
+// This is the whole of what replaces the session. It opens the readme in the
+// folder she pointed at, or the description in a package.json beside it, and
+// hands back one line. There is no queue, no model and no network in it, which
+// is the point: the sentence on screen says the answer comes back in a few
+// seconds, and this is the only version of the task that can keep that promise.
+//
+// The judgement about what makes a good line is in shared/first-run-line.mjs,
+// where the tests are. This file only reads.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { firstRunAnswer } from '../shared/first-run-line.mjs';
+import { DEPTH, SKIP, projectSentence } from '../shared/first-run-shape.mjs';
+
+/**
+ * The names a readme is actually called, in the order worth trying. Case is
+ *  not assumed: a folder listing is cheap and `readme.md` is common. */
+const README = ['README.md', 'README', 'README.txt', 'README.markdown', 'readme.md'];
+
+/**
+ * As much of a readme as could possibly hold its first sentence. A readme is
+ *  sometimes a book, and the whole of one has no business in memory here. */
+const READ_BYTES = 64 * 1024;
+
+function readHead(file) {
+  let fd = null;
+  try {
+    fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(READ_BYTES);
+    const n = fs.readSync(fd, buf, 0, READ_BYTES, 0);
+    return buf.slice(0, n).toString('utf8');
+  } catch {
+    return null;
+  } finally {
+    if (fd != null) { try { fs.closeSync(fd); } catch { /* nothing to do */ } }
+  }
+}
+
+/**
+ * The readme at the top of a folder, whatever it is called. Only the top
+ *  level, which is the bound she took as recommended on round four: "Read the
+ *  readme and the top level of this folder, and nothing deeper than that." */
+export function readReadme(folder) {
+  if (!folder) return null;
+  for (const name of README) {
+    const file = path.join(folder, name);
+    if (fs.existsSync(file)) return readHead(file);
+  }
+  // A folder whose readme is spelled some other way. One listing, top level.
+  let entries = [];
+  try { entries = fs.readdirSync(folder); } catch { return null; }
+  const hit = entries.find((e) => /^readme(\.|$)/i.test(e));
+  return hit ? readHead(path.join(folder, hit)) : null;
+}
+
+/**
+ * The one field in a manifest that says what a thing is. package.json is the
+ *  common case by a distance; the other two cost two lines each. */
+export function readDescription(folder) {
+  if (!folder) return null;
+  const pkg = path.join(folder, 'package.json');
+  if (fs.existsSync(pkg)) {
+    try {
+      const d = JSON.parse(fs.readFileSync(pkg, 'utf8')).description;
+      if (typeof d === 'string' && d.trim()) return d.trim();
+    } catch { /* a package.json that does not parse is not a description */ }
+  }
+  for (const name of ['pyproject.toml', 'Cargo.toml']) {
+    const file = path.join(folder, name);
+    if (!fs.existsSync(file)) continue;
+    const m = readHead(file)?.match(/^\s*description\s*=\s*["']([^"'\n]+)["']/m);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+/**
+ * THE DESCRIPTION, when the folder has one written down. Never throws: a
+ *  folder deleted between the name screen and this one still gets a sentence,
+ *  because the walk is not allowed to stop on it.
+ *
+ * This is NOT the task's answer any more, and says why: measured over the 29
+ * project folders in ~/Desktop/dev on 2026-08-21, only 16 of them have a line
+ * anywhere that says what the project is. It is what goes UNDER THE PROJECT'S
+ * NAME IN THE SIDEBAR, which is the job it was wanted for. */
+export function describeFor({ folder, name, shortFolder }) {
+  try {
+    return firstRunAnswer({
+      readme: readReadme(folder),
+      description: readDescription(folder),
+      name,
+      folder: shortFolder ?? folder,
+    });
+  } catch {
+    return firstRunAnswer({ readme: null, description: null, name, folder: shortFolder ?? folder });
+  }
+}
+
+/**
+ * THE GUARDED FOLDERS AS FULL PATHS, for the walk to refuse to enter.
+ *
+ * The picker refuses these as a project (shared/project-folder-check.mjs) and
+ * that is the door a tester actually walked through. This is the second door.
+ * The walk is three levels deep, so ANY caller that hands it the home folder
+ * makes it read ~/Desktop, ~/Downloads, ~/Music, ~/Pictures, ~/Movies,
+ * ~/Documents and ~/Library, and macOS answers each one with a consent panel
+ * carrying our name. Measured on 2026-08-25 against a real home folder: 4,001
+ * listings, every one of the seven touched, and 137 apps under Application
+ * Support plus 706 under Containers read by name. All of that to say "20,000
+ * files across 7,053 folders".
+ *
+ *  Matched as WHOLE PATHS directly under the home folder, never by name. A
+ *  project called `Documents` inside somebody's code folder is their project;
+ *  `~/Documents` is not. A project INSIDE a guarded folder still counts
+ *  normally, because the walk starts below the guard. */
+function guardedPaths(home) {
+  const h = String(home ?? '').replace(/\/+$/, '');
+  if (!h) return new Set();
+  return new Set(
+    ['Desktop', 'Documents', 'Downloads', 'Movies', 'Music', 'Pictures', 'Library', 'Public']
+      .map((n) => path.join(h, n)),
+  );
+}
+
+/**
+ * WHAT IS ACTUALLY IN THE FOLDER. Three levels deep, skipping everything that
+ *  is not the person's own work, never entering a folder macOS guards, and
+ *  stopping at a hard cap so a folder with a million files in it cannot turn a
+ *  two second promise into a long one. */
+export function countFolder(folder, { cap = 20_000, home = os.homedir() } = {}) {
+  const out = { files: 0, dirs: 0, ext: Object.create(null), newest: 0, capped: false };
+  const guarded = guardedPaths(home);
+  const walk = (dir, depth) => {
+    if (out.files >= cap) { out.capped = true; return; }
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (out.files >= cap) { out.capped = true; return; }
+      if (e.name.startsWith('.') || SKIP.has(e.name)) continue;
+      const p = path.join(dir, e.name);
+      // Counted as a folder, never opened. The number stays honest and macOS
+      // is never asked.
+      if (guarded.has(p)) { out.dirs += 1; continue; }
+      if (e.isDirectory()) { out.dirs += 1; if (depth > 0) walk(p, depth - 1); continue; }
+      out.files += 1;
+      const ext = path.extname(e.name);
+      if (ext) out.ext[ext] = (out.ext[ext] ?? 0) + 1;
+      try { const m = fs.statSync(p).mtimeMs; if (m > out.newest) out.newest = m; } catch { /* a file that vanished mid-walk is not a failure */ }
+    }
+  };
+  walk(folder, DEPTH);
+  return out;
+}
+
+/**
+ * Git's own words for when the folder last changed, or null when it is not a
+ *  repo. Its answer is better than a file's timestamp, which a checkout or a
+ *  build can move without anybody having written anything. */
+export function lastCommit(folder) {
+  try {
+    // GIT_DIR beats `-C`, so a shell that exported one (a git hook does, and so
+    // does anything launched from inside one) would have every folder answer
+    // with THAT repository's last commit, repo or not. Ask about the folder.
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) if (key.startsWith('GIT_')) delete env[key];
+    const out = execFileSync('git', ['-C', folder, 'log', '-1', '--format=%cr'], {
+      stdio: ['ignore', 'pipe', 'ignore'], timeout: 2_000, env,
+    }).toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * THE FIRST TASK'S ANSWER.The sentence is ours and every number in it is read
+ * off the folder chosen two screens earlier, so it is true about any project
+ * and cannot be a guess about what that project is. Never throws. */
+export function answerFor({ folder, name }) {
+  try {
+    const count = countFolder(folder);
+    return projectSentence({ ...count, name, lastCommit: lastCommit(folder) });
+  } catch {
+    return projectSentence({ name, files: 0, dirs: 0, ext: {} });
+  }
+}

package/main/folders.mjs

@@ -0,0 +1,91 @@
+// WALKING THE DISK FOR A SCREEN THAT CANNOT OPEN A MAC DIALOG.
+//
+// THE MISUNDERSTANDING THIS FILE EXISTS TO CORRECT. A browser tab cannot be
+// handed a real path by the operating system: the file input gives a page a
+// blob and a bare filename, on purpose, because a web page is not trusted with
+// somebody's disk. That is true and it is not going to change.
+//
+// It is also not the problem. The thing that needs to read the disk is not the
+// tab, it is the process the terminal started, and that process is ordinary
+// Node running as the person who typed the command. It has exactly the same
+// access the desktop app has. So the tab never asks the operating system for a
+// path. It asks the app what is in a folder, draws the answer, and sends back
+// the folder she clicked. The picker is ours instead of the Mac's, and the
+// answer is a real absolute path either way.
+//
+// This is how every editor in a browser does it, and it is the only part of
+// the desktop app that needed replacing rather than reusing.
+//
+// WHAT IS DELIBERATELY NOT HERE. No serving of file CONTENTS, and no walking
+// upward past the root. This lists directory names so somebody can point at
+// one. The folder it ends up pointing at still goes through
+// checkProjectFolder, the same as a path the Mac's own dialog returned.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Where the picker opens when nothing has been chosen yet. */
+export const startingPoint = (home = os.homedir()) => home;
+
+/**
+ * Resolve what a screen typed or clicked into an absolute path.
+ *
+ *  `~` is how our own screens write the home folder, and somebody typing a path
+ *  by hand writes it that way too.
+ */
+export function absolute(at, home = os.homedir()) {
+  const s = String(at ?? '').trim();
+  if (!s) return startingPoint(home);
+  if (s === '~') return home;
+  if (s.startsWith('~/')) return path.join(home, s.slice(2));
+  return path.resolve(s);
+}
+
+/**
+ * The folders inside one folder, and the way back up.
+ *
+ *  Returns `{ at, parent, home, folders }`, or `{ at, unreadable }` when the
+ *  folder is gone or the system will not open it. Unreadable is an ordinary
+ *  answer rather than a throw: somebody navigating a disk lands on a folder
+ *  they cannot open fairly often, and the screen should say so and stay put.
+ */
+export function listFolders({ at, home = os.homedir(), showHidden = false } = {}) {
+  const here = absolute(at, home);
+  const parent = path.dirname(here);
+
+  let entries;
+  try {
+    entries = fs.readdirSync(here, { withFileTypes: true });
+  } catch (err) {
+    return {
+      at: here,
+      parent: parent === here ? null : parent,
+      home,
+      folders: [],
+      unreadable: err.code === 'EACCES' || err.code === 'EPERM'
+        ? 'The system will not let this be opened.'
+        : 'That folder is not there any more.',
+    };
+  }
+
+  const folders = entries
+    .filter((entry) => {
+      // A symlink to a directory is a directory as far as somebody choosing a
+      // project folder is concerned, and plenty of real checkouts are one.
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) return false;
+      if (!showHidden && entry.name.startsWith('.')) return false;
+      return true;
+    })
+    .map((entry) => ({ name: entry.name, path: path.join(here, entry.name) }))
+    .filter((folder) => {
+      if (!folder.path) return false;
+      // A symlink that points at a file, or at nothing, is not a folder to walk
+      // into. statSync follows it; a broken one throws and is dropped.
+      try { return fs.statSync(folder.path).isDirectory(); } catch { return false; }
+    })
+    // The way a person reads a folder listing, not the way the disk returns it.
+    .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+
+  return { at: here, parent: parent === here ? null : parent, home, folders };
+}

package/main/fresh-user.mjs

@@ -0,0 +1,120 @@
+// OPEN A SECOND AGENTBOX AS SOMEBODY WHO HAS NEVER OPENED AGENTBOX.
+//
+// Two halves, and this file is the first one. The second half — walking the
+// onboarding again inside the app she already has — is `restartFirstRun` in
+// `renderer/src/onboarding.ts`, and it is the small one: it forgets that the
+// walk was finished and forgets nothing else. Being a NEW USER is bigger than
+// that. A new user has no projects, no settings, no theme, no store and no
+// config file, and there was no way to be one on a downloaded app except to
+// throw the install away, because `npm run fresh` needs a repo beside it and a
+// terminal in front of it and a downloaded app has neither.
+//
+// So this launches THE RUNNING APP AGAIN, inside a throwaway home. The recipe
+// is `shared/fresh-user-home.mjs`, which is the one `scripts/fresh-user.mjs`
+// has used since 2026-08-20, so there is one place it is written down.
+//
+// NOTHING OF HERS IS TOUCHED. Nothing is deleted, nothing is copied out, and
+// her own Agentbox keeps running with every agent in it: the single-instance
+// lock is keyed on userData, a throwaway home is a different userData, so the
+// two take separate locks and stand side by side. That is the property the
+// whole thing rests on, and it is why this may not be written as a reset.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { HOMES, existingHomes, prepareHome, makeHome, freshEnv } from '../shared/fresh-user-home.mjs';
+import { NAME } from '../shared/product-name.mjs';
+
+/**
+ * What to run, and what to hand it.
+ *
+ *  PACKAGED IS THE CASE THAT MATTERS, because the whole ask is about a
+ *  downloaded app: `process.execPath` is `Astral.app/Contents/MacOS/Astral`
+ *  and it takes no arguments.
+ *
+ *  UNPACKAGED IT IS ELECTRON, and Electron on its own opens its default window
+ *  rather than this app, so the app directory has to be handed back to it.
+ *  `process.argv[1]` is that directory when Agentbox is run from source. This
+ *  half exists so the row can be driven in a test and in a dev window rather
+ *  than only in a build, which is the difference between a feature that is
+ *  checked and one that is hoped for. */
+export function relaunchCommand({ execPath = process.execPath, argv = process.argv, packaged = true } = {}) {
+  if (packaged) return { bin: execPath, args: [] };
+  const appPath = argv[1];
+  return { bin: execPath, args: appPath ? [appPath] : [] };
+}
+
+/**
+ * Open one. Returns what happened, in the words the app will show her: this
+ *  is reported to the window rather than thrown, because a row in ⌘K that
+ *  fails silently is worse than one that says why.
+ *
+ *  `withAgents` defaults ON. A new user of THIS product already has Claude
+ *  Code, and the walk's last card offers to bring their agents over, so a
+ *  fresh copy that cannot see any agent files tests a screen no real user of
+ *  hers will ever get. Measured 2026-08-22: plain `npm run fresh` hides
+ *  `~/.claude`, and the walk's agent beat then says there is nothing to bring.
+ *  It cannot break inbox zero: the walk shows only its own three examples. */
+export function openFreshUser({
+  withAgents = true,
+  execPath = process.execPath,
+  argv = process.argv,
+  packaged = true,
+  spawnFn = spawn,
+  now,
+} = {}) {
+  let prepared;
+  try {
+    prepared = prepareHome(makeHome(now), { withAgents });
+  } catch (err) {
+    return { ok: false, error: `Could not make a throwaway home under ${HOMES}: ${err?.message ?? err}` };
+  }
+
+  const { bin, args } = relaunchCommand({ execPath, argv, packaged });
+  if (!bin || !fs.existsSync(bin)) {
+    return { ok: false, error: `Cannot find this app's own program at ${bin}.`, home: prepared.home };
+  }
+
+  let child;
+  try {
+    child = spawnFn(bin, args, {
+      detached: true,
+      stdio: 'ignore',
+      env: freshEnv(prepared.home),
+    });
+    child.unref?.();
+  } catch (err) {
+    return { ok: false, error: `Could not start a second ${NAME}: ${err?.message ?? err}`, home: prepared.home };
+  }
+
+  // THE NOTES ARE THE HONEST PART. Both of these are things a fresh copy can
+  // be missing without looking broken, and a test that quietly cannot run an
+  // agent is a test that lies. They are said rather than assumed.
+  const notes = [];
+  if (!prepared.claudeBin) notes.push('Claude Code is not at ~/.local/bin/claude, so agents will not run in it.');
+  if (!prepared.keychain) notes.push('There is no ~/Library/Keychains here, so Claude Code will say it is not logged in.');
+  if (withAgents && !prepared.agents) notes.push('There is no ~/.claude on this Mac, so it will have no agents to offer.');
+
+  return { ok: true, home: prepared.home, agents: prepared.agents, notes, pid: child?.pid ?? null };
+}
+
+/**
+ * The leftovers, so the app can say how many there are rather than growing a
+ *  folder under /tmp nobody ever looks at. */
+export function freshUserHomes() {
+  return { root: HOMES, homes: existingHomes() };
+}
+
+/**
+ * Delete every throwaway home. Only ever the /tmp folder this file made:
+ *  `HOMES` is not configurable, and that is on purpose. */
+export function clearFreshUserHomes() {
+  try {
+    fs.rmSync(HOMES, { recursive: true, force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+export { HOMES, path as _path };