scoops 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alphaq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# arivu
+
+> *arivu* (அறிவு) — Tamil for **knowledge, wisdom**
+
+Persistent knowledge base for Claude Code. Gives your AI agent memory that survives across sessions.
+
+## The Problem
+
+Every new Claude Code session starts with zero context. The agent re-explores your codebase, rediscovers the same dead ends, and forgets every architectural decision you made yesterday.
+
+**arivu fixes this.** It maintains a living knowledge base about your project — and injects only what's relevant, based on what you're actually working on.
+
+## How It Works
+
+```
+You type: "add rate limiting to the auth routes"
+                    ↓
+        arivu reads your prompt
+        matches keywords against .arivu/index.json
+        pulls the 3 most relevant knowledge entries
+                    ↓
+    [Architecture] Auth middleware (src/middleware/auth.ts)
+      Verifies JWT from httpOnly cookie
+      Gotcha: jose v5 — use SignJWT class, not jwt.sign()
+
+    [Thread] Auth system — IN PROGRESS
+      Remaining: token refresh flow, rate limiting on auth routes
+
+    [Decision] Use jose for JWT, not jsonwebtoken
+      Why: jsonwebtoken has known CVEs
+                    ↓
+        Injected into Claude's context automatically
+        Agent knows exactly where to start — no re-exploration
+```
+
+Three Claude Code hooks do the work:
+- **SessionStart** — announces what's in memory (~30 tokens)
+- **UserPromptSubmit** — matches your prompt to relevant knowledge (~200 tokens, surgically targeted)
+- **Stop** — enforces a knowledge update if you made code changes
+
+## Install
+
+```bash
+npx arivu init
+```
+
+That's it. Run it in any project.
+
+## What Gets Created
+
+```
+.arivu/
+  decisions.json      — why things are the way they are
+  architecture.json   — how components connect and work
+  threads.json        — what's in progress, what's next
+  warnings.json       — dead ends and traps to avoid
+  index.json          — lightweight tag index for fast retrieval
+  hooks/
+    session-start.js
+    prompt-retriever.js
+    stop-gate.js
+
+.claude/
+  settings.json       — hook configuration (merged, not overwritten)
+```
+
+All files are committed to git. Teammates get the knowledge base automatically when they clone.
+
+## Knowledge Schema
+
+### decisions.json
+```json
+{
+  "id": "d_a1b2c3d4",
+  "decision": "Use jose for JWT, not jsonwebtoken",
+  "why": "jsonwebtoken has known CVEs, jose supports ESM",
+  "alternatives_rejected": ["jsonwebtoken"],
+  "tags": ["auth", "jwt", "security"],
+  "affects": ["src/auth/*"],
+  "date": "2026-03-26"
+}
+```
+
+### architecture.json
+```json
+{
+  "id": "a_e5f6g7h8",
+  "component": "Auth middleware",
+  "location": "src/middleware/auth.ts",
+  "does": "Verifies JWT from httpOnly cookie, attaches user to req",
+  "depends_on": ["jose"],
+  "depended_by": ["all /api/admin/* routes"],
+  "tags": ["auth", "middleware", "jwt"],
+  "gotchas": ["jose v5: use SignJWT class, not jwt.sign()"]
+}
+```
+
+### threads.json
+```json
+{
+  "id": "t_i9j0k1l2",
+  "thread": "Auth system",
+  "status": "in_progress",
+  "done": ["JWT generation", "login route"],
+  "remaining": ["token refresh", "rate limiting"],
+  "tags": ["auth", "jwt"],
+  "blocked_by": null,
+  "updated": "2026-03-26"
+}
+```
+
+### warnings.json
+```json
+{
+  "id": "w_m2n3o4p5",
+  "warning": "bcrypt segfaults on M1 Macs in this Node version",
+  "context": "Spent 45min debugging — switched to argon2",
+  "avoid": "Do not add bcrypt as a dependency",
+  "tags": ["auth", "hashing"],
+  "date": "2026-03-25"
+}
+```
+
+## CLI Commands
+
+```bash
+arivu init                      # Set up in current project
+arivu status                    # Check everything is wired up
+arivu list                      # View all knowledge entries
+arivu list --type decisions     # Filter by type
+arivu list --tag auth           # Filter by tag
+arivu prune --keep 50           # Keep only last 50 entries
+arivu prune --before 2026-01-01 # Remove entries older than date
+arivu export --format md        # Export as markdown
+arivu export --format json      # Export as JSON
+```
+
+## Design Principles
+
+- **Zero dependencies** — Node.js built-ins only
+- **Standalone hooks** — work even if you uninstall arivu
+- **Smart retrieval** — keyword scoring, not "dump everything"
+- **Git-tracked** — knowledge is version-controlled and team-shared
+- **Never crashes** — all hooks exit 0 on any error
+
+## License
+
+MIT

package/bin/arivu.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli.js');

package/bin/ascr.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli.js');

package/bin/scoops.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli.js');

package/bin/zute.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli.js');

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "scoops",
+  "version": "0.1.0",
+  "description": "Persistent knowledge base for Claude Code — context that survives across sessions",
+  "bin": {
+    "scoops": "bin/scoops.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "context",
+    "ai",
+    "cli",
+    "knowledge",
+    "ascr"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test src/**/*.test.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const { readFileSync } = require('node:fs');
+const { join } = require('node:path');
+
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const HELP = `
+ascr — Automated Semantic Context Registry
+
+USAGE
+  ascr <command> [options]
+
+COMMANDS
+  init              Set up ASCR in the current project
+  status            Check if ASCR is correctly configured
+  list              View knowledge base entries
+  prune             Remove old or irrelevant entries
+  export            Export knowledge base as markdown or JSON
+
+OPTIONS
+  --help, -h        Show this help message
+  --version, -v     Show version
+
+EXAMPLES
+  ascr init
+  ascr list --tag auth
+  ascr list --type decisions
+  ascr prune --keep 50
+  ascr export --format md
+`.trim();
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    help:    { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false },
+  },
+  strict: false,
+});
+
+if (values.version) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const command = positionals[0];
+
+if (!command || values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const commands = {
+  init:   () => require('./commands/init'),
+  status: () => require('./commands/status'),
+  list:   () => require('./commands/list'),
+  prune:  () => require('./commands/prune'),
+  export: () => require('./commands/export'),
+};
+
+if (!commands[command]) {
+  console.error(`ascr: unknown command '${command}'\nRun 'ascr --help' for usage.`);
+  process.exit(1);
+}
+
+// Pass remaining args (skip the command itself)
+process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+commands[command]();

package/src/commands/export.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const fs = require('node:fs');
+const { readAllKnowledge } = require('../lib/memory');
+
+const { values } = parseArgs({
+  options: {
+    format: { type: 'string', short: 'f', default: 'md' },
+    output: { type: 'string', short: 'o' },
+  },
+  strict: false,
+});
+
+const cwd = process.cwd();
+const format = values.format;
+
+if (!['md', 'json'].includes(format)) {
+  console.error(`Unknown format '${format}'. Use --format md or --format json`);
+  process.exit(1);
+}
+
+const knowledge = readAllKnowledge(cwd);
+const totalEntries = Object.values(knowledge).reduce((n, arr) => n + arr.length, 0);
+const now = new Date().toISOString();
+
+let output = '';
+
+if (format === 'json') {
+  output = JSON.stringify(knowledge, null, 2) + '\n';
+} else {
+  const lines = [];
+  lines.push('# ASCR Knowledge Base Export');
+  lines.push(`Generated: ${now}`);
+  lines.push(`Total entries: ${totalEntries}`);
+  lines.push('');
+
+  // Decisions
+  if (knowledge.decisions.length > 0) {
+    lines.push('## Decisions');
+    lines.push('*Why things are the way they are.*');
+    lines.push('');
+    for (const e of knowledge.decisions) {
+      lines.push(`### ${e.decision || e.id}`);
+      if (e.why) lines.push(`**Why:** ${e.why}`);
+      if (e.alternatives_rejected?.length) lines.push(`**Alternatives rejected:** ${e.alternatives_rejected.join(', ')}`);
+      if (e.affects?.length) lines.push(`**Affects:** ${e.affects.join(', ')}`);
+      if (e.tags?.length) lines.push(`**Tags:** ${e.tags.join(', ')}`);
+      if (e.date) lines.push(`**Date:** ${e.date}`);
+      lines.push('');
+    }
+  }
+
+  // Architecture
+  if (knowledge.architecture.length > 0) {
+    lines.push('## Architecture');
+    lines.push('*How components connect and work.*');
+    lines.push('');
+    for (const e of knowledge.architecture) {
+      lines.push(`### ${e.component || e.id}`);
+      if (e.location) lines.push(`**Location:** \`${e.location}\``);
+      if (e.does) lines.push(`**Does:** ${e.does}`);
+      if (e.depends_on?.length) lines.push(`**Depends on:** ${e.depends_on.join(', ')}`);
+      if (e.depended_by?.length) lines.push(`**Used by:** ${e.depended_by.join(', ')}`);
+      if (e.gotchas?.length) { lines.push('**Gotchas:**'); e.gotchas.forEach(g => lines.push(`- ${g}`)); }
+      if (e.tags?.length) lines.push(`**Tags:** ${e.tags.join(', ')}`);
+      lines.push('');
+    }
+  }
+
+  // Threads
+  if (knowledge.threads.length > 0) {
+    lines.push('## Threads');
+    lines.push('*What\'s in progress and what\'s next.*');
+    lines.push('');
+    for (const e of knowledge.threads) {
+      lines.push(`### ${e.thread || e.id} — ${(e.status || '?').toUpperCase()}`);
+      if (e.done?.length) { lines.push('**Done:**'); e.done.forEach(d => lines.push(`- ${d}`)); }
+      if (e.remaining?.length) { lines.push('**Remaining:**'); e.remaining.forEach(r => lines.push(`- ${r}`)); }
+      if (e.blocked_by) lines.push(`**Blocked by:** ${e.blocked_by}`);
+      if (e.tags?.length) lines.push(`**Tags:** ${e.tags.join(', ')}`);
+      if (e.updated) lines.push(`**Updated:** ${e.updated}`);
+      lines.push('');
+    }
+  }
+
+  // Warnings
+  if (knowledge.warnings.length > 0) {
+    lines.push('## Warnings');
+    lines.push('*Dead ends, traps, and things to avoid.*');
+    lines.push('');
+    for (const e of knowledge.warnings) {
+      lines.push(`### ${e.warning || e.id}`);
+      if (e.context) lines.push(`**Context:** ${e.context}`);
+      if (e.avoid) lines.push(`**Avoid:** ${e.avoid}`);
+      if (e.tags?.length) lines.push(`**Tags:** ${e.tags.join(', ')}`);
+      if (e.date) lines.push(`**Date:** ${e.date}`);
+      lines.push('');
+    }
+  }
+
+  if (totalEntries === 0) {
+    lines.push('*No entries yet. Start a Claude Code session and build something!*');
+    lines.push('');
+  }
+
+  output = lines.join('\n');
+}
+
+if (values.output) {
+  fs.writeFileSync(values.output, output, 'utf8');
+  console.log(`Exported ${totalEntries} entries to ${values.output}`);
+} else {
+  process.stdout.write(output);
+}

package/src/commands/init.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+const paths = require('../lib/paths');
+const { mergeHooksIntoSettings } = require('../lib/merge-settings');
+
+const { values } = parseArgs({
+  options: { force: { type: 'boolean', short: 'f', default: false } },
+  strict: false,
+});
+
+const cwd = process.cwd();
+const ascrDir = paths.ascrDir(cwd);
+const alreadyExists = fs.existsSync(ascrDir) && fs.existsSync(paths.decisionsFile(cwd));
+
+if (alreadyExists && !values.force) {
+  console.log('ASCR is already initialized in this project.');
+  console.log('Run `ascr init --force` to re-initialize and update hooks.');
+  process.exit(0);
+}
+
+const created = [];
+const updated = [];
+
+// ── 1. Create .ascr/ directories ──────────────────────────────────────────────
+fs.mkdirSync(paths.hooksDir(cwd), { recursive: true });
+
+// ── 2. Create empty knowledge files (only if not present) ────────────────────
+const knowledgeFiles = {
+  'decisions.json':    paths.decisionsFile(cwd),
+  'architecture.json': paths.architectureFile(cwd),
+  'threads.json':      paths.threadsFile(cwd),
+  'warnings.json':     paths.warningsFile(cwd),
+  'index.json':        paths.indexFile(cwd),
+};
+
+const emptyIndex = JSON.stringify({ decisions: [], architecture: [], threads: [], warnings: [] }, null, 2) + '\n';
+
+for (const [name, file] of Object.entries(knowledgeFiles)) {
+  if (!fs.existsSync(file) || values.force) {
+    const content = name === 'index.json' ? emptyIndex : '[]\n';
+    fs.writeFileSync(file, content, 'utf8');
+    created.push(`.ascr/${name}`);
+  }
+}
+
+// ── 3. Create .ascr/.gitignore ─────────────────────────────────────────────────
+const gitignorePath = paths.gitignoreFile(cwd);
+const gitignoreContent = '# ASCR session state (ephemeral — do not commit)\n.session-hash-*\n';
+if (!fs.existsSync(gitignorePath) || values.force) {
+  fs.writeFileSync(gitignorePath, gitignoreContent, 'utf8');
+  created.push('.ascr/.gitignore');
+}
+
+// ── 4. Copy hook scripts from package source ──────────────────────────────────
+const hookSources = {
+  'session-start.js':   path.join(__dirname, '..', 'hooks', 'session-start.js'),
+  'prompt-retriever.js':path.join(__dirname, '..', 'hooks', 'prompt-retriever.js'),
+  'stop-gate.js':       path.join(__dirname, '..', 'hooks', 'stop-gate.js'),
+};
+
+for (const [name, src] of Object.entries(hookSources)) {
+  const dest = path.join(paths.hooksDir(cwd), name);
+  const content = fs.readFileSync(src, 'utf8');
+  const exists = fs.existsSync(dest);
+  fs.writeFileSync(dest, content, 'utf8');
+  if (exists) updated.push(`.ascr/hooks/${name}`);
+  else created.push(`.ascr/hooks/${name}`);
+}
+
+// ── 5. Create or merge .claude/settings.json ─────────────────────────────────
+fs.mkdirSync(paths.claudeDir(cwd), { recursive: true });
+const settingsPath = paths.settingsFile(cwd);
+let existingSettings = {};
+
+if (fs.existsSync(settingsPath)) {
+  try {
+    existingSettings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    console.error(`\nError: .claude/settings.json is malformed JSON. Please fix it before running ascr init.`);
+    process.exit(1);
+  }
+}
+
+const mergedSettings = mergeHooksIntoSettings(existingSettings);
+fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2) + '\n', 'utf8');
+if (fs.existsSync(settingsPath) && JSON.stringify(existingSettings) !== '{}') {
+  updated.push('.claude/settings.json');
+} else {
+  created.push('.claude/settings.json');
+}
+
+// ── 6. Print summary ──────────────────────────────────────────────────────────
+console.log('');
+if (created.length > 0) {
+  for (const f of created) console.log(`  Created:  ${f}`);
+}
+if (updated.length > 0) {
+  for (const f of updated) console.log(`  Updated:  ${f}`);
+}
+
+console.log('');
+console.log('ASCR initialized! Start a new Claude Code session to activate.');
+console.log('');
+console.log('How it works:');
+console.log('  • Each prompt → relevant knowledge injected automatically');
+console.log('  • After making code changes → you must update .ascr/ before ending');
+console.log('  • Run `ascr status` to verify setup');

package/src/commands/list.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const paths = require('../lib/paths');
+const { readKnowledge, TYPES, filterEntries } = require('../lib/memory');
+
+const { values } = parseArgs({
+  options: {
+    type:    { type: 'string',  short: 't' },
+    tag:     { type: 'string' },
+    status:  { type: 'string' },
+    json:    { type: 'boolean', default: false },
+    last:    { type: 'string' },
+  },
+  strict: false,
+});
+
+const cwd = process.cwd();
+const typeFilter = values.type;
+const typesToShow = typeFilter ? [typeFilter] : TYPES;
+const last = values.last ? parseInt(values.last, 10) : null;
+
+if (typeFilter && !TYPES.includes(typeFilter)) {
+  console.error(`Unknown type '${typeFilter}'. Valid: ${TYPES.join(', ')}`);
+  process.exit(1);
+}
+
+let hasAny = false;
+
+for (const type of typesToShow) {
+  let entries = readKnowledge(cwd, type);
+  entries = filterEntries(entries, { tag: values.tag, status: values.status });
+  if (last) entries = entries.slice(-last);
+  if (entries.length === 0) continue;
+  hasAny = true;
+
+  if (values.json) {
+    console.log(JSON.stringify({ [type]: entries }, null, 2));
+    continue;
+  }
+
+  console.log(`\n── ${type.toUpperCase()} (${entries.length}) ─────────────────────────────────`);
+  for (const e of entries) {
+    switch (type) {
+      case 'decisions':
+        console.log(`  [${e.id || '?'}] ${e.decision}`);
+        if (e.why) console.log(`       Why: ${e.why}`);
+        if (e.tags?.length) console.log(`       Tags: ${e.tags.join(', ')}`);
+        if (e.date) console.log(`       Date: ${e.date}`);
+        break;
+      case 'architecture':
+        console.log(`  [${e.id || '?'}] ${e.component} — ${e.location || 'no location'}`);
+        if (e.does) console.log(`       ${e.does}`);
+        if (e.tags?.length) console.log(`       Tags: ${e.tags.join(', ')}`);
+        if (e.gotchas?.length) console.log(`       Gotchas: ${e.gotchas.join(' | ')}`);
+        break;
+      case 'threads':
+        console.log(`  [${e.id || '?'}] ${e.thread} — ${(e.status || '?').toUpperCase()}`);
+        if (e.remaining?.length) console.log(`       Remaining: ${e.remaining.join(', ')}`);
+        if (e.blocked_by) console.log(`       Blocked by: ${e.blocked_by}`);
+        if (e.tags?.length) console.log(`       Tags: ${e.tags.join(', ')}`);
+        break;
+      case 'warnings':
+        console.log(`  [${e.id || '?'}] ${e.warning}`);
+        if (e.avoid) console.log(`       Avoid: ${e.avoid}`);
+        if (e.tags?.length) console.log(`       Tags: ${e.tags.join(', ')}`);
+        if (e.date) console.log(`       Date: ${e.date}`);
+        break;
+    }
+    console.log('');
+  }
+}
+
+if (!hasAny) {
+  const ctx = typeFilter ? `in '${typeFilter}'` : 'in any knowledge file';
+  console.log(`\nNo entries found ${ctx}.`);
+  if (!paths.decisionsFile(cwd).includes('.ascr')) {
+    console.log('Run `ascr init` to set up ASCR first.');
+  }
+  console.log('');
+}