@gafj/gafj 0.1.1 → 0.1.3

package/README.md

@@ -28,7 +28,7 @@ Status: phases 1 through 6 built and tested (82 public tests on the synthetic ca
 - Bullet register (screen 6): `house_rules.bullet_register` is `result_first` (default, RAS), `action_first`, or `posting`; it travels in the resume packet's HOUSE RULES and `core/rules/resume.md` says what each means. Same facts, same claims, same gate; only word order.
 - Backup folder (screen 6): `config.backup_dir`, meant for a synced folder (Drive, OneDrive, Dropbox); `store/backup_dir.js` writes dated consistent copies there (`gafj backup`, the Back up now button, and one a day at `serve` start), keeps the newest 14, never prunes a pre-restore copy, and refuses the data folder itself. The live store never goes to a synced folder.
 - Hosted tier (plan W, gates 2 and 4 as code): `http/hosted.js` runs the same routes, screens, and doors behind a Google sign-in with one store per user under `<root>/tenants/<uid>/`; the session names the uid, the uid names the folder, and no query spans tenants (`test/hosted.test.js` drives every parameterized route as user B with user A's ids and expects 404 and no leaked text). Provider keys, MCP config, and the restore test are 404 for hosted users; the model is reached through the relay with a service key and the uid (`x-gafj-service`, `x-gafj-uid`; the relay's second auth path), never a stored user token. `/account/export` streams a restorable backup, `/account/delete` removes the folder and every session. `http/identity.js` verifies Firebase ID tokens with node:crypto against Google's JWK set, no SDK. `ui/hosted/signin.html` is the one page with a loosened CSP (Firebase Auth from gstatic). `gafj serve-hosted` is configured by environment only; `deploy/hosted/` holds the Dockerfile and fly.toml; `functions/relay/deploy.js` builds the relay with Firebase Admin, Stripe, and the Anthropic SDK and `functions/index.js` exports it as `relay`. Nothing is deployed; `docs/operator-setup.md` is the list of what only the operator can do.
-- `bin/cli.js`: `migrate`, `import`, `snapshot`, `review`, `lint`, `list`, `score-freeze`, `packet`, `ingest`, `render`, `export`, `backup`, `restore`, `mcp`, `print-mcp-config`, `serve`, `url`, `rotate-token`, `install-startup`, `allow-host`, `init`, `onboard`; every other command names its phase and exits
+- `bin/cli.js`: `start` (the one command: candidate if none, then url or serve), `migrate`, `import`, `snapshot`, `review`, `lint`, `list`, `score-freeze`, `packet`, `ingest`, `render`, `export`, `backup`, `restore`, `mcp`, `print-mcp-config`, `serve`, `url`, `rotate-token`, `install-startup`, `allow-host`, `init`, `onboard`; every other command names its phase and exits
 
 Onboarding another candidate, phase 5b:
 

package/bin/cli.js

@@ -39,6 +39,7 @@ const COMMANDS = {
   render: "write a passed document as Markdown: render --document <id> [--out <dir>]",
   list: "list ids: list postings|applications|interviews|documents|runs",
   mcp: "run the stdio MCP server for Claude Desktop or Claude Code (stdout is the wire)",
+  start: "the one command: creates your candidate the first time (asks your name), then opens the app: start [--name <name>]",
   serve: "run the local UI server on 127.0.0.1: serve [--port <n>] [--force] [--no-open]",
   url: "print a fresh launch URL for the running server (and open the browser): url [--no-open] [--host <allowed host>] [--qr]",
   "allow-host": "let a local HTTPS proxy front the server for your phone: allow-host <name.tail1234.ts.net> | allow-host --remove <name>",
@@ -487,10 +488,35 @@ async function main(argv) {
     } finally { db.close(); }
   }
 
+  if (cmd === "start") {
+    // One command for a new user and for every day after: make the candidate if there is none (asking the
+    // name once), then open the app: a fresh launch link if the server is up, otherwise serve.
+    const { readLock, pidAlive } = require("../http/server");
+    if (!cfg.candidate_id) {
+      let name = opts.name ? String(opts.name) : "";
+      if (!name && process.stdin.isTTY) {
+        const rl = require("readline").createInterface({ input: process.stdin, output: process.stdout });
+        name = await new Promise((resolve) => rl.question("Your name, as it should appear on a resume: ", (a) => { rl.close(); resolve(String(a || "").trim()); }));
+      }
+      name = name || "Candidate";
+      const db = openStore(home);
+      try {
+        const id = ulid(Date.now());
+        db.prepare("INSERT INTO candidate (id, name, created_at) VALUES (?, ?, ?)").run(id, name, nowIso());
+        cfg.candidate_id = id;
+        writeConfig(home.dir, cfg);
+        require("../store/onboarding").openBatch(db, { candidate_id: id, now: nowIso(), actor: ACTOR("start") });
+      } finally { db.close(); }
+      out(`welcome, ${name}. Your data lives in ${home.dir}`);
+    }
+    const lock = readLock(home.dir);
+    return main(lock && pidAlive(lock.pid) ? ["url"] : ["serve"]);
+  }
+
   if (cmd === "serve") {
     const { createServer, ensureSessionToken, readLock, writeLock, removeLock, pidAlive } = require("../http/server");
     const pkg = require("../package.json");
-    if (!cfg.candidate_id) { process.stderr.write("no candidate yet; run gafj import first\n"); process.exit(2); }
+    if (!cfg.candidate_id) { process.stderr.write("no candidate yet; run gafj start\n"); process.exit(2); }
     const lock = readLock(home.dir);
     if (lock && pidAlive(lock.pid) && !opts.force) {
       out(`gafj serve is already running (pid ${lock.pid}) at http://127.0.0.1:${lock.port}; run "gafj url" for a launch link, or serve --force`);

package/http/api.js

@@ -151,6 +151,12 @@ route("GET", "/api/kb/questions", (c, p, b, q) => discover.listQuestions(c.db, c
 route("POST", "/api/kb/questions/:id/answer", (c, p, b) => discover.answerQuestion(c.db, { candidate_id: c.candidate_id, question_id: p.id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("answer_question") }));
 route("POST", "/api/kb/questions/:id/dismiss", (c, p) => discover.dismissQuestion(c.db, { candidate_id: c.candidate_id, question_id: p.id, now: c.now(), actor: ACTOR("dismiss_question") }));
 
+// guided setup (first run)
+const setup = require("../store/setup");
+route("GET", "/api/setup", (c) => setup.setupView(c.db, c.home, c.candidate_id));
+route("POST", "/api/setup/ai", (c, p, b) => { const r = setup.chooseAi(c.db, c.home, c.candidate_id, { route: need(b, "route"), now: c.now(), actor: ACTOR("setup") }); if (c.reload) c.reload(); return r; });
+route("POST", "/api/setup/dismiss", (c, p, b) => setup.dismiss(c.db, c.home, c.candidate_id, { dismissed: b.dismissed !== false }));
+
 // settings (screen 6)
 const settings = require("../store/settings");
 route("GET", "/api/settings", (c) => settings.getSettings(c.db, c.home, c.candidate_id));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gafj/gafj",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "GAF-J: a local campaign engine for job search. One SQLite file, one ingest door, your own AI subscription.",
   "homepage": "https://gaf-j.com",
   "repository": {

package/store/setup.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * The guided setup (first run): six steps in the order they must happen,
+ * each computed from the store, so the checklist is never out of date and
+ * nothing is stored except two flags in config: which AI route the user
+ * chose on purpose (the default is paste, which says nothing), and whether
+ * they dismissed the card. The card leaves on its own when every step is done.
+ */
+
+const { readConfig, writeConfig } = require("./config");
+
+const ROUTE_LABEL = { paste: "Paste", mcp: "Claude Desktop", byo_key: "My providers", credits: "Credits" };
+
+function setupView(db, homeDir, candidate_id) {
+  const cfg = readConfig(homeDir);
+  const one = (sql, ...a) => db.prepare(sql).get(...a).c;
+  const sources = one("SELECT count(*) c FROM source_document WHERE candidate_id = ?", candidate_id);
+  const extracted = one("SELECT count(*) c FROM ai_run WHERE candidate_id = ? AND operation = 'extract' AND final_result = 'passed'", candidate_id);
+  const pending = one("SELECT count(*) c FROM pending_accomplishment WHERE candidate_id = ?", candidate_id);
+  const confirmed = one("SELECT count(*) c FROM accomplishment WHERE candidate_id = ?", candidate_id);
+  const questions = one("SELECT count(*) c FROM kb_question WHERE candidate_id = ?", candidate_id);
+  const postings = one("SELECT count(*) c FROM posting WHERE candidate_id = ?", candidate_id);
+  const aiChosen = !!(cfg.setup && cfg.setup.ai_chosen);
+  const steps = [
+    { key: "ai", title: "Tell GAF-J which AI you use", done: aiChosen, detail: aiChosen ? `Using ${ROUTE_LABEL[cfg.route] || cfg.route}` : null },
+    { key: "upload", title: "Upload your resumes", done: sources > 0, detail: sources ? `${sources} file${sources === 1 ? "" : "s"} uploaded` : null },
+    { key: "extract", title: "Extract records from them", done: extracted > 0 || pending > 0 || confirmed > 0, detail: extracted ? `${extracted} extraction${extracted === 1 ? "" : "s"} saved` : null },
+    { key: "confirm", title: "Confirm the records you stand behind", done: confirmed > 0, detail: confirmed ? `${confirmed} confirmed${pending ? `, ${pending} still pending` : ""}` : (pending ? `${pending} waiting for you` : null) },
+    { key: "discover", title: "Answer what's missing", done: questions > 0, detail: questions ? `${questions} question${questions === 1 ? "" : "s"} asked` : null },
+    { key: "posting", title: "Paste your first job posting", done: postings > 0, detail: postings ? `${postings} posting${postings === 1 ? "" : "s"}` : null },
+  ];
+  const next = steps.find((s) => !s.done);
+  return { steps, next: next ? next.key : null, complete: !next, dismissed: !!(cfg.setup && cfg.setup.dismissed), route: cfg.route || "paste" };
+}
+
+/** The user picked how they will use AI; the route is set and the step is done. */
+function chooseAi(db, homeDir, candidate_id, { route, now, actor }) {
+  const settings = require("./settings");
+  settings.putSettings(db, homeDir, candidate_id, { route }, { now, actor });
+  const cfg = readConfig(homeDir);
+  cfg.setup = { ...(cfg.setup || {}), ai_chosen: true };
+  writeConfig(homeDir, cfg);
+  return setupView(db, homeDir, candidate_id);
+}
+
+function dismiss(db, homeDir, candidate_id, { dismissed = true } = {}) {
+  const cfg = readConfig(homeDir);
+  cfg.setup = { ...(cfg.setup || {}), dismissed: !!dismissed };
+  writeConfig(homeDir, cfg);
+  return setupView(db, homeDir, candidate_id);
+}
+
+module.exports = { setupView, chooseAi, dismiss };

package/ui/app.css

@@ -135,3 +135,19 @@ input.narrow { width: 76px; }
 pre.wrap { white-space: pre-wrap; }
 /* KB "receipt" moment: the confirmed span highlighted inline against its muted source sentence. */
 mark { background: var(--good-bg); color: var(--good-bright); border-radius: 3px; padding: 0 3px; font-weight: 500; }
+
+/* guided setup on the dashboard: the next step is open with its words and its button; done steps collapse to a line */
+.setup { margin-top: 10px; border-color: var(--accent); }
+.setup-steps { list-style: none; margin: 10px 0 0; padding: 0; }
+.setup-steps li { display: grid; grid-template-columns: 28px 1fr; gap: 10px; padding: 9px 0; border-top: 1px solid var(--line); align-items: start; }
+.setup-steps li:first-child { border-top: 0; }
+.setup-steps .n { width: 24px; height: 24px; border-radius: 50%; border: 1px solid var(--line-2); display: inline-flex; align-items: center; justify-content: center; font-size: 11px; color: var(--muted); }
+.setup-steps li.done .n { background: var(--good-bg); color: var(--good-bright); border-color: var(--good-bg); }
+.setup-steps li.next .n { border-color: var(--accent); color: var(--accent); font-weight: 600; }
+.setup-steps li.done .t { color: var(--muted); }
+.setup-steps li.later .t { color: var(--dim); }
+.setup-steps li.next .t { font-weight: 600; }
+.setup-steps p { margin: 4px 0 8px; color: var(--muted); max-width: 66ch; }
+.ai-options { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 8px; margin-top: 4px; }
+.ai-options button { text-align: left; display: flex; flex-direction: column; gap: 4px; padding: 10px 12px; height: 100%; }
+.ai-options button:hover { border-color: var(--accent); }

package/ui/screens/dashboard.js

@@ -1,11 +1,49 @@
 import { html, useState, useEffect } from "../vendor/preact.mjs";
 import { api, fmtWhen } from "../lib.js";
 
+/** The six steps a new user takes, in order, with the words for each and where the button goes. */
+const STEPS = {
+  ai: { why: "GAF-J never writes text itself. It hands a packet of your confirmed facts to an AI you already have, then checks every figure in the reply. Pick how you will connect one; you can change it later in Settings.", cta: null },
+  upload: { why: "Every resume you have, old ones too. Word, PDF, Markdown, or plain text. The text is read on this PC; nothing is uploaded anywhere.", cta: ["#/kb", "Open Knowledge base"] },
+  extract: { why: "Beside each uploaded file, click Extract. A packet opens: copy it into your AI, paste its JSON reply back. Your AI proposes records where every number and phrase is quoted from the file; anything it cannot quote is refused.", cta: ["#/kb", "Extract on Knowledge base"] },
+  confirm: { why: "Under Pending, read each proposed record. Confirm the ones you can stand behind in an interview, edit what is off, dismiss the rest. Only confirmed records can ever appear in a document.", cta: ["#/kb", "Review Pending"] },
+  discover: { why: "Click Ask what's missing. Your AI reads the confirmed records and asks the questions a coach would: the figure a record lacks, the size of a team, the story behind a bare bullet. Each answer strengthens a record.", cta: ["#/kb", "Ask what's missing"] },
+  posting: { why: "Paste the text of a job you want. GAF-J scores it against your record, shows what the posting asks for and what you have, and from there builds the resume, the interview prep, and the rest.", cta: ["#/postings", "Paste a posting"] },
+};
+const AI_OPTIONS = [
+  ["paste", "Paste", "Works with any chat you already pay for: ChatGPT, Claude, Gemini. Copy the packet, paste the reply. No keys, no setup."],
+  ["mcp", "Claude Desktop", "Claude talks to the app directly through a local connector. Print the config in Settings and add it to Claude Desktop."],
+  ["byo_key", "My own API key", "The app calls the provider itself with a key you add in Settings. The key never leaves this PC."],
+];
+
+function Setup({ s, reload }) {
+  const [busy, setBusy] = useState(false);
+  const choose = async (route) => { setBusy(true); try { await api.post("/api/setup/ai", { route }); await reload(); } finally { setBusy(false); } };
+  const done = s.steps.filter((x) => x.done).length;
+  return html`<div class="card setup">
+    <div class="row between"><b>Getting started: ${done} of ${s.steps.length}</b><button class="small" onClick=${async () => { await api.post("/api/setup/dismiss", {}); reload(); }}>hide</button></div>
+    <ol class="setup-steps">${s.steps.map((st, i) => {
+      const meta = STEPS[st.key];
+      const isNext = s.next === st.key;
+      return html`<li key=${st.key} class=${st.done ? "done" : isNext ? "next" : "later"}>
+        <span class="n mono">${st.done ? "✓" : i + 1}</span>
+        <div>
+          <div class="t">${st.title}${st.detail ? html` <span class="muted small">· ${st.detail}</span>` : ""}</div>
+          ${isNext ? html`<p class="small">${meta.why}</p>
+            ${st.key === "ai" ? html`<div class="ai-options">${AI_OPTIONS.map(([r, label, text]) => html`<button key=${r} disabled=${busy} onClick=${() => choose(r)}><b>${label}</b><span class="small muted">${text}</span></button>`)}</div>`
+              : html`<div class="row"><a href=${meta.cta[0]}><button class="primary small">${meta.cta[1]}</button></a></div>`}` : ""}
+        </div></li>`;
+    })}</ol>
+  </div>`;
+}
+
 export function Dashboard({ live }) {
   const [snap, setSnap] = useState(null);
+  const [setup, setSetup] = useState(null);
   const [msg, setMsg] = useState("");
   const [err, setErr] = useState("");
-  useEffect(() => { api.get("/api/snapshot").then(setSnap).catch((e) => setErr(e.message)); }, [live]);
+  const loadSetup = () => api.get("/api/setup").then(setSetup).catch(() => setSetup(null));
+  useEffect(() => { api.get("/api/snapshot").then(setSnap).catch((e) => setErr(e.message)); loadSetup(); }, [live]);
   const act = async (path, label) => { setMsg(""); setErr(""); try { const r = await api.post(path); setMsg(`${label}: ${r.file}`); } catch (e) { setErr(e.message); } };
   if (err && !snap) return html`<p class="error">${err}</p>`;
   if (!snap) return html`<p class="muted">loading</p>`;
@@ -13,6 +51,8 @@ export function Dashboard({ live }) {
   return html`<div>
     <h1>Dashboard</h1>
     <div class="sub">${new Date(snap.now).toLocaleString()}</div>
+    ${setup && !setup.complete && !setup.dismissed ? html`<${Setup} s=${setup} reload=${loadSetup} />` : ""}
+    ${setup && !setup.complete && setup.dismissed ? html`<p class="small muted">Setup is hidden. <a href="#/" onClick=${async (e) => { e.preventDefault(); await api.post("/api/setup/dismiss", { dismissed: false }); loadSetup(); }}>Show the steps again</a>.</p>` : ""}
     <h2>Needs you now</h2>
     <div class="card">${snap.needs_you.length ? html`<ul class="list">${snap.needs_you.map((n, i) => html`<li key=${i}>
       <span class=${"need " + (n.kind === "thankyou_due" || n.kind === "review" ? "soft" : "")}>●</span> <a href=${link(n)}>${n.text}</a></li>`)}</ul>` : html`<span class="muted">nothing waiting on you</span>`}</div>

package/ui/screens/postings.js

@@ -37,6 +37,25 @@ export function Postings({ live, id }) {
   const [rows, setRows] = useState([]);
   const [sel, setSel] = useState(null);
   const [form, setForm] = useState({ company: "", title: "", source_url: "", location: "", comp_text: "", raw_text: "" });
+  const [guessed, setGuessed] = useState({ company: true, title: true });
+  // the paste is all a person should have to give; company and title are guessed from its first lines and can be corrected
+  const onPaste = (text) => {
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).slice(0, 12);
+    const next = { ...form, raw_text: text };
+    if (guessed.title) {
+      const t = lines.find((l) => l.length <= 90 && !/^https?:/i.test(l) && !/^(at|company|location|posted|apply|share)\b/i.test(l));
+      next.title = t || "";
+    }
+    if (guessed.company) {
+      let c = "";
+      for (const l of lines) { const m = l.match(/^(?:at|company[:\s]+|employer[:\s]+)\s*([^|·,]{2,60})/i); if (m) { c = m[1].trim(); break; } }
+      if (!c) { const i = lines.findIndex((l) => l === next.title); const cand = lines[i + 1] || ""; if (cand && cand.length <= 50 && !/^https?:/i.test(cand) && !/\d{4}/.test(cand)) c = cand.replace(/^[·|\-\s]+/, ""); }
+      next.company = c;
+    }
+    const url = lines.find((l) => /^https?:\/\//i.test(l));
+    if (url && !form.source_url) next.source_url = url;
+    setForm(next);
+  };
   const [err, setErr] = useState("");
   const [msg, setMsg] = useState("");
   const load = async () => { setRows(await api.get("/api/postings")); if (id) setSel(await api.get(`/api/postings/${id}`)); };
@@ -47,6 +66,7 @@ export function Postings({ live, id }) {
       const r = await api.post("/api/postings", form);
       await api.post(`/api/postings/${r.posting_id}/scan`);
       setForm({ company: "", title: "", source_url: "", location: "", comp_text: "", raw_text: "" });
+      setGuessed({ company: true, title: true });
       location.hash = "#/postings/" + r.posting_id;
       setMsg(r.created ? "stored and scanned" : "already stored; scanned again");
     } catch (e2) { setErr(e2.message); }
@@ -61,10 +81,10 @@ export function Postings({ live, id }) {
       <div>
         <h2>Paste posting</h2>
         <form class="card" onSubmit=${store}>
-          <div class="row"><input required placeholder="company" value=${form.company} onInput=${(e) => setForm({ ...form, company: e.target.value })} /><input required placeholder="title" value=${form.title} onInput=${(e) => setForm({ ...form, title: e.target.value })} /></div>
-          <div class="row"><input placeholder="url" value=${form.source_url} onInput=${(e) => setForm({ ...form, source_url: e.target.value })} /><input placeholder="location" value=${form.location} onInput=${(e) => setForm({ ...form, location: e.target.value })} /><input placeholder="comp text" value=${form.comp_text} onInput=${(e) => setForm({ ...form, comp_text: e.target.value })} /></div>
-          <textarea required placeholder="raw posting text, stored verbatim, now" value=${form.raw_text} onInput=${(e) => setForm({ ...form, raw_text: e.target.value })}></textarea>
-          <div class="row"><button class="primary">Store + scan</button><span class="small muted">local, no model</span></div>
+          <textarea required placeholder="Paste the whole job posting here, exactly as the site shows it. Company and title fill in below from what you paste." value=${form.raw_text} onInput=${(e) => onPaste(e.target.value)}></textarea>
+          <div class="row"><input required placeholder="company (guessed from the paste; fix if wrong)" value=${form.company} onInput=${(e) => { setGuessed({ ...guessed, company: false }); setForm({ ...form, company: e.target.value }); }} /><input required placeholder="title (guessed; fix if wrong)" value=${form.title} onInput=${(e) => { setGuessed({ ...guessed, title: false }); setForm({ ...form, title: e.target.value }); }} /></div>
+          <div class="row"><input placeholder="link to the posting (optional)" value=${form.source_url} onInput=${(e) => setForm({ ...form, source_url: e.target.value })} /></div>
+          <div class="row"><button class="primary">Store + scan</button><span class="small muted">stored on this PC and scored locally; no AI is called for this step</span></div>
         </form>
         <h2>Stored</h2>
         <div class="card"><ul class="list">${rows.map((r) => html`<li key=${r.posting_id}><a href=${"#/postings/" + r.posting_id}>${r.company}: ${r.title}</a> <span class="tag">${r.status}</span> ${r.scoring_frozen ? html`<span class="tag passed">frozen</span>` : html`<span class="tag warn">unscored</span>`} ${r.application_id ? html`<a class="small" href=${"#/applications/" + r.application_id}>application</a>` : ""} ${r.taken_down_at ? html`<span class="tag warn">taken down</span>` : ""}</li>`)}${rows.length ? "" : html`<li class="muted">none yet</li>`}</ul></div>