@staff0rd/assist 0.62.0 → 0.64.0

package/README.md

@@ -36,6 +36,8 @@ After installation, the `assist` command will be available globally.
 - `/refactor` - Run refactoring checks for code quality
 - `/restructure` - Analyze and restructure tightly-coupled files
 - `/review-comments` - Process PR review comments one by one
+- `/journal` - Append a journal entry summarising recent work, decisions, and notable observations
+- `/standup` - Summarise recent journal entries as a standup update
 - `/verify` - Run all verification commands in parallel
 - `/transcript-format` - Format meeting transcripts from VTT files
 - `/transcript-summarise` - Summarise transcripts missing summaries
@@ -57,7 +59,7 @@ After installation, the `assist` command will be available globally.
 - `assist backlog add` - Add a new backlog item interactively
 - `assist backlog start <id>` - Set a backlog item to in-progress
 - `assist backlog done <id>` - Set a backlog item to done
-- `assist roam auth` - Configure Roam API credentials (saved to ~/.assist.yml)
+- `assist roam auth` - Authenticate with Roam via OAuth (opens browser, saves tokens to ~/.assist.yml)
 - `assist run <name>` - Run a configured command from assist.yml
 - `assist run add` - Add a new run configuration to assist.yml
 - `assist config set <key> <value>` - Set a config value (e.g. commit.push true)

package/claude/commands/journal.md

@@ -0,0 +1,74 @@
+---
+description: Append a journal entry summarising recent work, decisions, and notable observations
+allowed_args: "[optional focus or note]"
+---
+
+Append a structured journal entry to today's daily file. This should be fast — do not read existing journal files or attempt to deduplicate.
+
+## Step 1: Determine the date and file
+
+**IMPORTANT:** Do not rely on your own sense of the current date — it may be stale in long-running sessions. Always run `date +%Y-%m-%d` and `date +%H:%M` via Bash to get the actual current date and time.
+
+The journal lives in `~/.claude/journal/`, one file per day, named `YYYY-MM-DD.md`.
+
+If today's file doesn't exist, create it with a heading:
+
+```markdown
+# YYYY-MM-DD
+```
+
+## Step 2: Resolve project context
+
+Determine the current project by matching the working directory against `~/.claude/skills/projects.json`. If not inside a registered project, use "general" as the project name.
+
+## Step 3: Write the entry
+
+Append an entry to the daily file. Each entry should follow this structure:
+
+```markdown
+## HH:MM — {project name} #{project name}
+
+{Summary of what was done — keep it concise but capture the key points}
+
+**Decisions:** {any notable decisions made and why, or "None"}
+
+**Topics:** {flag anything blog-worthy, reusable, or worth revisiting — or "None"}
+```
+
+Tag the project name in the heading (e.g., `#project1`, `#general`). When flagging topics, prefix with `#blog-worthy`, `#reusable`, or `#demo-worthy`:
+
+Guidelines:
+
+- Summarise what was accomplished, not every step taken
+- Capture the "why" behind decisions — this is what you'll forget
+- Flag blog-worthy topics with a brief note on why it's interesting
+- Flag reusable patterns, utilities, or approaches worth extracting
+- Flag demo-worthy work — things that would make a good presentation, show-and-tell, or live walkthrough
+- If the user provided `$ARGUMENTS`, use it to focus or annotate the entry
+- Keep entries concise — a few lines per section, not paragraphs
+
+## Step 4: Write detail files (when topics are flagged)
+
+When a topic is flagged as blog-worthy or reusable, create a supporting detail file that captures the context needed to act on it later. Without this, the journal flags opportunities but loses the detail needed to follow through.
+
+Detail files live in `~/.claude/journal/details/` and are named `YYYY-MM-DD-{slug}.md`.
+
+Link them from the journal entry:
+
+```markdown
+**Topics:**
+
+- #blog-worthy Teaching Claude to reflect — [detail](details/2026-02-13-reflect-workflow.md)
+- #reusable The skill/hook pattern — [detail](details/2026-02-13-starter-kit.md)
+```
+
+Each detail file should include whichever of the following are relevant:
+
+- **Context** — what problem was being solved and why
+- **Approach** — what was tried, including dead ends and alternatives considered
+- **Key code** — relevant snippets, patterns, or configurations that were created
+- **Outcome** — what worked, what didn't, and why
+- **Blog angle** — if blog-worthy, what makes it interesting to write about
+- **Extraction notes** — if reusable, what could be extracted and how it might be generalised
+
+These files are meant to preserve enough context that someone (including a future Claude session) could flesh out a blog post or extract reusable code without the original conversation.

package/claude/commands/standup.md

@@ -0,0 +1,35 @@
+---
+description: Summarise recent journal entries as a standup update
+allowed_args: "[days back, default 1] [project name]"
+---
+
+Summarise recent journal entries.
+
+## Step 1: Determine the range
+
+Parse `$ARGUMENTS` for:
+
+- A number (days to look back, default 1)
+- A project name (filter to that project only, default all)
+
+Examples:
+
+- `/standup` — yesterday's entries, all projects
+- `/standup 3` — last 3 days, all projects
+- `/standup project1` — yesterday's entries for project1
+- `/standup 7 project2` — last 7 days for project2
+
+## Step 2: Read journal files
+
+Read the daily files from `~/.claude/journal/` for the date range. Files are named `YYYY-MM-DD.md`.
+
+## Step 3: Present the summary
+
+Summarise the entries concisely, grouped by day and project. Highlight:
+
+- What was accomplished
+- Key decisions made
+- Any flagged blog topics or reusable IP
+- Anything left in progress
+
+Keep it brief — this is a standup, not a report.

package/claude/settings.json

@@ -27,6 +27,7 @@
 			"Bash(assist transcript summarise:*)",
 			"Bash(assist complexity:*)",
 			"Bash(assist transcript format:*)",
+			"Bash(date:*)",
 			"Bash(git add:*)",
 			"Bash(git status:*)",
 			"Bash(git show:*)",
@@ -36,6 +37,7 @@
 			"Bash(gh repo view:*)",
 			"Bash(gh pr checks:*)",
 			"Bash(gh pr view:*)",
+			"Bash(gh pr list:*)",
 			"Bash(gh pr diff:*)",
 			"Bash(gh run view:*)",
 			"SlashCommand(/next-backlog-item)",
@@ -46,6 +48,8 @@
 			"SlashCommand(/review-comments)",
 			"SlashCommand(/transcript-format)",
 			"SlashCommand(/transcript-summarise)",
+			"SlashCommand(/journal)",
+			"SlashCommand(/standup)",
 			"Skill(next-backlog-item)",
 			"Skill(verify)",
 			"Skill(commit)",
@@ -54,6 +58,8 @@
 			"Skill(review-comments)",
 			"Skill(transcript-format)",
 			"Skill(transcript-summarise)",
+			"Skill(journal)",
+			"Skill(standup)",
 			"WebFetch(domain:staffordwilliams.com)"
 		],
 		"deny": ["Bash(git commit:*)", "Bash(npm run:*)", "Bash(npx assist:*)"]

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.62.0",
+  version: "0.64.0",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -112,7 +112,10 @@ var assistConfigSchema = z.strictObject({
   }).optional(),
   roam: z.strictObject({
     clientId: z.string(),
-    clientSecret: z.string()
+    clientSecret: z.string(),
+    accessToken: z.string().optional(),
+    refreshToken: z.string().optional(),
+    tokenExpiresAt: z.number().optional()
   }).optional(),
   run: z.array(runConfigSchema).optional(),
   transcript: transcriptConfigSchema.optional()
@@ -4111,9 +4114,9 @@ function addChildMoves(moves, children, newDir, parentBase) {
   for (const child of children)
     moves.push(childMoveData(child, newDir, parentBase));
 }
-function checkDirConflict(result, label, dir) {
+function checkDirConflict(result, label2, dir) {
   if (!fs20.existsSync(dir)) return false;
-  result.warnings.push(`Skipping ${label}: directory ${dir} already exists`);
+  result.warnings.push(`Skipping ${label2}: directory ${dir} already exists`);
   return true;
 }
 function getBaseName(filePath) {
@@ -4266,8 +4269,8 @@ function askQuestion(rl, question) {
 }
 
 // src/commands/transcript/configure.ts
-function buildPrompt(label, current) {
-  return current ? `${label} [${current}]: ` : `${label}: `;
+function buildPrompt(label2, current) {
+  return current ? `${label2} [${current}]: ` : `${label2}: `;
 }
 function printExisting(existing) {
   console.log("Current configuration:");
@@ -4618,10 +4621,10 @@ function logSkipped(relativeDir, mdFile) {
   console.log(`Skipping (already exists): ${join18(relativeDir, mdFile)}`);
   return "skipped";
 }
-function ensureDirectory(dir, label) {
+function ensureDirectory(dir, label2) {
   if (!existsSync19(dir)) {
     mkdirSync5(dir, { recursive: true });
-    console.log(`Created ${label}: ${dir}`);
+    console.log(`Created ${label2}: ${dir}`);
   }
 }
 function processCues(content) {
@@ -4860,28 +4863,203 @@ function registerVerify(program2) {
 }
 
 // src/commands/roam/auth.ts
+import { randomBytes } from "crypto";
 import chalk49 from "chalk";
-import enquirer6 from "enquirer";
-async function auth() {
-  const { clientId } = await enquirer6.prompt({
-    type: "input",
-    name: "clientId",
-    message: "Client ID:",
-    validate: (value) => value.trim().length > 0 || "Client ID is required"
+
+// src/lib/openBrowser.ts
+import { execSync as execSync23 } from "child_process";
+function tryExec(commands) {
+  for (const cmd of commands) {
+    try {
+      execSync23(cmd);
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function openBrowser(url) {
+  const platform = detectPlatform();
+  const quoted = JSON.stringify(url);
+  const commands = [];
+  switch (platform) {
+    case "macos":
+      commands.push(
+        `open -a "Google Chrome" ${quoted}`,
+        `open -a "Microsoft Edge" ${quoted}`,
+        `open -a "Safari" ${quoted}`
+      );
+      break;
+    case "linux":
+      commands.push(
+        `google-chrome ${quoted}`,
+        `chromium-browser ${quoted}`,
+        `microsoft-edge ${quoted}`
+      );
+      break;
+    case "windows":
+      commands.push(`start chrome ${quoted}`, `start msedge ${quoted}`);
+      break;
+    case "wsl":
+      commands.push(`wslview ${quoted}`);
+      break;
+  }
+  if (!tryExec(commands)) {
+    console.log(`Open this URL in Chrome, Edge, or Safari:
+${url}`);
+  }
+}
+
+// src/commands/roam/waitForCallback.ts
+import { createServer } from "http";
+function respondHtml(res, status, title) {
+  res.writeHead(status, { "Content-Type": "text/html" });
+  res.end(
+    `<html><body><h1>${title}</h1><p>You can close this tab.</p></body></html>`
+  );
+}
+function extractCode(url, expectedState) {
+  const error = url.searchParams.get("error");
+  if (error) throw new Error(`Authorization denied: ${error}`);
+  const state = url.searchParams.get("state");
+  if (state !== expectedState)
+    throw new Error("State mismatch \u2014 possible CSRF attack");
+  const code = url.searchParams.get("code");
+  if (!code) throw new Error("No authorization code received");
+  return code;
+}
+function waitForCallback(port, expectedState) {
+  return new Promise((resolve3, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("Authorization timed out after 120 seconds"));
+    }, 12e4);
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      clearTimeout(timeout);
+      try {
+        const code = extractCode(url, expectedState);
+        respondHtml(res, 200, "Authorization successful!");
+        server.close();
+        resolve3(code);
+      } catch (err) {
+        respondHtml(res, 400, err.message);
+        server.close();
+        reject(err);
+      }
+    });
+    server.listen(port);
+  });
+}
+
+// src/commands/roam/authorizeInBrowser.ts
+var PORT = 14523;
+var REDIRECT_URI = `http://localhost:${PORT}/callback`;
+var SCOPES = "user:read meetings:read transcript:read user:read.email";
+function buildAuthorizeUrl(clientId, state) {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: REDIRECT_URI,
+    response_type: "code",
+    scope: SCOPES,
+    state
+  });
+  return `https://ro.am/oauth/authorize?${params}`;
+}
+async function authorizeInBrowser(clientId, state) {
+  openBrowser(buildAuthorizeUrl(clientId, state));
+  const code = await waitForCallback(PORT, state);
+  return { code, redirectUri: REDIRECT_URI };
+}
+
+// src/commands/roam/exchangeToken.ts
+async function exchangeToken(params) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    client_id: params.clientId,
+    client_secret: params.clientSecret,
+    redirect_uri: params.redirectUri
+  });
+  const response = await fetch("https://ro.am/oauth/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
   });
-  const { clientSecret } = await enquirer6.prompt({
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${text}`);
+  }
+  return response.json();
+}
+
+// src/commands/roam/promptCredentials.ts
+import enquirer6 from "enquirer";
+function censor(value) {
+  const visible = value.slice(-4);
+  return `${"*".repeat(value.length - 4)}${visible}`;
+}
+function label(name, existing) {
+  return existing ? `${name} (${censor(existing)})` : name;
+}
+async function promptField(name, existing) {
+  const { value } = await enquirer6.prompt({
     type: "input",
-    name: "clientSecret",
-    message: "Client Secret:",
-    validate: (value) => value.trim().length > 0 || "Client Secret is required"
+    name: "value",
+    message: `${label(name, existing)}:`,
+    validate: (v) => v.trim().length > 0 || !!existing || `${name} is required`
   });
+  return value.trim() || existing || "";
+}
+async function promptCredentials(existing) {
+  const clientId = await promptField("Client ID", existing?.clientId);
+  const clientSecret = await promptField(
+    "Client Secret",
+    existing?.clientSecret
+  );
+  if (!clientId || !clientSecret) {
+    throw new Error("Client ID and Client Secret are required");
+  }
+  return { clientId, clientSecret };
+}
+
+// src/commands/roam/auth.ts
+async function auth() {
   const config = loadGlobalConfig();
+  const { clientId, clientSecret } = await promptCredentials(config.roam);
+  config.roam = { ...config.roam, clientId, clientSecret };
+  saveGlobalConfig(config);
+  const state = randomBytes(16).toString("hex");
+  console.log(
+    chalk49.yellow("\nEnsure this Redirect URI is set in your Roam OAuth app:")
+  );
+  console.log(chalk49.white("http://localhost:14523/callback\n"));
+  console.log(chalk49.blue("Opening browser for authorization..."));
+  console.log(chalk49.dim("Waiting for authorization callback..."));
+  const { code, redirectUri } = await authorizeInBrowser(clientId, state);
+  console.log(chalk49.dim("Exchanging code for tokens..."));
+  const tokens = await exchangeToken({
+    code,
+    clientId,
+    clientSecret,
+    redirectUri
+  });
   config.roam = {
-    clientId: clientId.trim(),
-    clientSecret: clientSecret.trim()
+    clientId,
+    clientSecret,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    tokenExpiresAt: Date.now() + tokens.expires_in * 1e3
   };
   saveGlobalConfig(config);
-  console.log(chalk49.green("Roam credentials saved to ~/.assist.yml"));
+  console.log(
+    chalk49.green("Roam credentials and tokens saved to ~/.assist.yml")
+  );
 }
 
 // src/commands/roam/registerRoam.ts
@@ -5109,7 +5287,7 @@ function syncCommands(claudeDir, targetBase) {
 }
 
 // src/commands/update.ts
-import { execSync as execSync23 } from "child_process";
+import { execSync as execSync24 } from "child_process";
 import * as path30 from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 var __filename3 = fileURLToPath4(import.meta.url);
@@ -5119,7 +5297,7 @@ function getInstallDir() {
 }
 function isGitRepo(dir) {
   try {
-    execSync23("git rev-parse --is-inside-work-tree", {
+    execSync24("git rev-parse --is-inside-work-tree", {
       cwd: dir,
       stdio: "pipe"
     });
@@ -5130,7 +5308,7 @@ function isGitRepo(dir) {
 }
 function isGlobalNpmInstall(dir) {
   try {
-    const globalPrefix = execSync23("npm prefix -g", { stdio: "pipe" }).toString().trim();
+    const globalPrefix = execSync24("npm prefix -g", { stdio: "pipe" }).toString().trim();
     return dir.startsWith(globalPrefix);
   } catch {
     return false;
@@ -5141,16 +5319,16 @@ async function update() {
   console.log(`Assist is installed at: ${installDir}`);
   if (isGitRepo(installDir)) {
     console.log("Detected git repo installation, pulling latest...");
-    execSync23("git pull", { cwd: installDir, stdio: "inherit" });
+    execSync24("git pull", { cwd: installDir, stdio: "inherit" });
     console.log("Building...");
-    execSync23("npm run build", { cwd: installDir, stdio: "inherit" });
+    execSync24("npm run build", { cwd: installDir, stdio: "inherit" });
     console.log("Syncing commands...");
-    execSync23("assist sync", { stdio: "inherit" });
+    execSync24("assist sync", { stdio: "inherit" });
   } else if (isGlobalNpmInstall(installDir)) {
     console.log("Detected global npm installation, updating...");
-    execSync23("npm i -g @staff0rd/assist@latest", { stdio: "inherit" });
+    execSync24("npm i -g @staff0rd/assist@latest", { stdio: "inherit" });
     console.log("Syncing commands...");
-    execSync23("assist sync", { stdio: "inherit" });
+    execSync24("assist sync", { stdio: "inherit" });
   } else {
     console.error(
       "Could not determine installation method. Expected a git repo or global npm install."

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.62.0",
+	"version": "0.64.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {