@yunhozz/arc 0.2.2 → 0.2.4

package/codex/skill/references/superpowers/brainstorming/visual-companion.md

@@ -1,299 +0,0 @@
-# Visual Companion Guide
-
-Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
-
-## When to Use
-
-Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
-
-**Use the browser** when the content itself is visual:
-
-- **UI mockups** — wireframes, layouts, navigation structures, component designs
-- **Architecture diagrams** — system components, data flow, relationship maps
-- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
-- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
-- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
-
-**Use the terminal** when the content is text or tabular:
-
-- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
-- **Conceptual A/B/C choices** — picking between approaches described in words
-- **Tradeoff lists** — pros/cons, comparison tables
-- **Technical decisions** — API design, data modeling, architectural approach selection
-- **Clarifying questions** — anything where the answer is words, not a visual preference
-
-A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
-
-## How It Works
-
-The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
-
-**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
-
-## Starting a Session
-
-```bash
-# Start AFTER the user approves the companion. --open auto-opens their browser on
-# the first screen; --project-dir persists mockups and enables same-port restart.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-
-# Returns: {"type":"server-started","port":52341,
-#           "url":"http://localhost:52341/?key=ab12…",
-#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
-#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
-```
-
-Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
-
-**The URL contains a session key (`?key=…`).** The server rejects any request
-without it, so always give the user the **complete** URL from the `url` field —
-never strip the query string, and never hand out a bare `http://host:port`. The
-key gates HTTP and WebSocket access so a stray browser tab or another machine on
-the network can't read the screens or inject events. After the first load the
-browser remembers the key via a cookie, so reloads and `/files/*` assets work
-without repeating it.
-
-**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
-
-**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
-
-**Launching the server by platform:**
-
-**Claude Code:**
-```bash
-# Default mode works — the script backgrounds the server itself.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-```
-
-On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
-
-**Codex:**
-```bash
-# Codex reaps background processes. The script auto-detects CODEX_CI and
-# switches to foreground mode. Run it normally — no extra flags needed.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-```
-
-**Gemini CLI:**
-```bash
-# Use --foreground and set is_background: true on your shell tool call
-# so the process survives across turns
-bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-**Copilot CLI:**
-```bash
-# Start it with Copilot CLI's non-blocking/background shell mechanism so the
-# server survives across turns. Keep --foreground so the harness, not the
-# script, owns backgrounding. The launcher is a .sh, so invoke it via bash
-# (on Windows, call Git Bash's bash.exe from the PowerShell tool).
-bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
-
-If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
-
-```bash
-bash scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-Use `--url-host` to control what hostname is printed in the returned URL JSON.
-
-## The Loop
-
-1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
-   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
-   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
-   - **Never reuse filenames** — each screen gets a fresh file
-   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
-   - Server automatically serves the newest file
-
-2. **Tell user what to expect and end your turn:**
-   - Remind them of the URL (every step, not just first)
-   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
-   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
-
-3. **On your next turn** — after the user responds in the terminal:
-   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
-   - Merge with the user's terminal text to get the full picture
-   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
-
-4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
-
-5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
-
-   ```html
-   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
-   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
-     <p class="subtitle">Continuing in terminal...</p>
-   </div>
-   ```
-
-   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
-
-6. Repeat until done.
-
-## Writing Content Fragments
-
-Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
-
-**Minimal example:**
-
-```html
-<h2>Which layout works better?</h2>
-<p class="subtitle">Consider readability and visual hierarchy</p>
-
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Single Column</h3>
-      <p>Clean, focused reading experience</p>
-    </div>
-  </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
-    <div class="letter">B</div>
-    <div class="content">
-      <h3>Two Column</h3>
-      <p>Sidebar navigation with main content</p>
-    </div>
-  </div>
-</div>
-```
-
-That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
-
-## CSS Classes Available
-
-The frame template provides these CSS classes for your content:
-
-### Options (A/B/C choices)
-
-```html
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Title</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
-
-```html
-<div class="options" data-multiselect>
-  <!-- same option markup — users can select/deselect multiple -->
-</div>
-```
-
-### Cards (visual designs)
-
-```html
-<div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup content --></div>
-    <div class="card-body">
-      <h3>Name</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-### Mockup container
-
-```html
-<div class="mockup">
-  <div class="mockup-header">Preview: Dashboard Layout</div>
-  <div class="mockup-body"><!-- your mockup HTML --></div>
-</div>
-```
-
-### Split view (side-by-side)
-
-```html
-<div class="split">
-  <div class="mockup"><!-- left --></div>
-  <div class="mockup"><!-- right --></div>
-</div>
-```
-
-### Pros/Cons
-
-```html
-<div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
-</div>
-```
-
-### Mock elements (wireframe building blocks)
-
-```html
-<div class="mock-nav">Logo | Home | About | Contact</div>
-<div style="display: flex;">
-  <div class="mock-sidebar">Navigation</div>
-  <div class="mock-content">Main content area</div>
-</div>
-<button class="mock-button">Action Button</button>
-<input class="mock-input" placeholder="Input field">
-<div class="placeholder">Placeholder area</div>
-```
-
-### Typography and sections
-
-- `h2` — page title
-- `h3` — section heading
-- `.subtitle` — secondary text below title
-- `.section` — content block with bottom margin
-- `.label` — small uppercase label text
-
-## Browser Events Format
-
-When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
-
-```jsonl
-{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
-{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
-{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
-```
-
-The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
-
-If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
-
-## Design Tips
-
-- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
-- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
-- **Iterate before advancing** — if feedback changes current screen, write a new version
-- **2-4 options max** per screen
-- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
-- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
-
-## File Naming
-
-- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
-- Never reuse filenames — each screen must be a new file
-- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
-- Server serves newest file by modification time
-
-## Cleaning Up
-
-```bash
-bash scripts/stop-server.sh $SESSION_DIR
-```
-
-If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
-
-## Reference
-
-- Frame template (CSS reference): `scripts/frame-template.html`
-- Helper script (client-side): `scripts/helper.js`

package/lib/policy/claude-hook.mjs

@@ -1,80 +0,0 @@
-import path from 'node:path';
-import {pathToFileURL} from 'node:url';
-// Only this fixed bootstrap is executed. The separately encoded path is data.
-const bootstrap="import(Buffer.from(process.argv[1],'base64').toString('utf8')).then(module=>module.runHook()).catch(()=>{process.stderr.write('ARC Git guard failed to load\\n');process.exitCode=2;});";
-const prefix=`node -e "eval(Buffer.from('${Buffer.from(bootstrap).toString('base64')}','base64').toString('utf8'))" `;
-export function buildClaudeHookCommand(scriptPath) {
-  if(typeof scriptPath!=='string'||/[\x00-\x1f]/.test(scriptPath)||!path.isAbsolute(scriptPath)&&!path.win32.isAbsolute(scriptPath))throw Error('Claude hook requires an absolute script path');
-  let url;
-  if(path.win32.isAbsolute(scriptPath)&&/^[A-Za-z]:[\\/]/.test(scriptPath)) {
-    const normalized=path.win32.normalize(scriptPath).replaceAll('\\','/');url='file:///'+normalized.split('/').map((part,i)=>i===0?part:encodeURIComponent(part)).join('/');
-  } else {if(!path.isAbsolute(scriptPath)||path.normalize(scriptPath)!==scriptPath)throw Error('Invalid absolute hook path');url=pathToFileURL(scriptPath).href;}
-  return prefix+`"${Buffer.from(url).toString('base64')}"`;
-}
-export const templateHookCommand=buildClaudeHookCommand('/__ARC_INSTALLED_SKILL__/hooks/role-git-guard.mjs');
-export function validateClaudeHookCommand(command) {
-  if(typeof command!=='string'||!command.startsWith(prefix))throw Error('Unmanaged Claude hook command');
-  const encoded=/^"([A-Za-z0-9+/]+={0,2})"$/.exec(command.slice(prefix.length));if(!encoded)throw Error('Invalid Claude hook command');
-  const decoded=Buffer.from(encoded[1],'base64');if(decoded.toString('base64')!==encoded[1])throw Error('Invalid hook path encoding');
-  const url=new URL(decoded.toString('utf8'));if(url.protocol!=='file:'||url.host||!['/hooks/role-git-guard.mjs','/hooks/runtime-gate.mjs'].some(suffix=>url.pathname.endsWith(suffix))||url.search||url.hash)throw Error('Invalid hook file URL');
-  return command;
-}
-function entry(command,matcher,eol){
- validateClaudeHookCommand(command);
- return [`    - matcher: ${matcher}`,'      hooks:','        - type: command',`          command: ${JSON.stringify(command)}`,'          onFailure: block'].join(eol);
-}
-function entries(skillPath,eol){
- return entry(buildClaudeHookCommand(path.join(skillPath,'hooks/role-git-guard.mjs')),'Bash',eol);
-}
-export function hookFrontmatter(command=templateHookCommand,eol='\n') {
- validateClaudeHookCommand(command);
- return ['hooks:','  PreToolUse:',entry(command,'Bash',eol)].join(eol);
-}
-function update(text,skillPath,requireManaged){
- const eol=/\r?\n/.exec(text)?.[0]??'\n';
- const fm=/^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/.exec(text);
- if(!fm)throw Error('Missing Claude frontmatter for hook generation');
- let lines=fm[1].split(/\r?\n/);
- const headers=lines.flatMap((line,i)=>/^hooks:/.test(line)?[i]:[]);
- if(headers.length>1)throw Error('Duplicate Claude hooks');
- let count=0;
- if(headers.length){
-  const h=headers[0];if(lines[h]!=='hooks:')throw Error('Malformed Claude hooks');
-  let end=h+1;while(end<lines.length&&(/^[ \t]/.test(lines[end])||lines[end]===''))end++;
-  const indexes=[];for(let i=h+1;i<end;i++)if(/^  PreToolUse:/.test(lines[i]))indexes.push(i);
-  if(indexes.length>1)throw Error('Duplicate PreToolUse');
-  if(indexes.length){
-   const pre=indexes[0];if(lines[pre]!=='  PreToolUse:')throw Error('Malformed PreToolUse');
-   let finish=pre+1;while(finish<end&&!/^  \S/.test(lines[finish]))finish++;
-   const kept=[];const seen=new Set();
-   for(let i=pre+1;i<finish;){
-    if(lines[i]===''){kept.push(lines[i++]);continue;}
-    if(!/^    - /.test(lines[i]))throw Error('Malformed Claude hook entry');
-    let j=i+1;while(j<finish&&!/^    - /.test(lines[j]))j++;
-    const chunk=lines.slice(i,j),body=chunk.join('\n');
-    const commands=chunk.filter(line=>/^          command: /.test(line));
-    const managed=commands.some(line=>{try{validateClaudeHookCommand(JSON.parse(line.slice('          command: '.length)));return true;}catch{return false;}});
-    if(managed){
-     if(commands.length!==1)throw Error('Malformed managed Claude hook');
-     const command=JSON.parse(commands[0].slice('          command: '.length));
-     const encoded=/"([A-Za-z0-9+/]+={0,2})"$/.exec(command)[1];const file=new URL(Buffer.from(encoded,'base64').toString('utf8')).pathname.split('/').at(-1);
-     if(seen.has(file))throw Error('Duplicate managed Claude hook');seen.add(file);count++;
-     const matcher=file==='runtime-gate.mjs'?'    - matcher: "*"':'    - matcher: Bash';
-     const base=[matcher,'      hooks:','        - type: command',commands[0]];
-     // Legacy four-line guard upgrades once; malformed failure behavior is never repaired silently.
-     if(JSON.stringify(chunk)!==JSON.stringify(base)&&JSON.stringify(chunk)!==JSON.stringify([...base,'          onFailure: block']))throw Error('Malformed managed Claude hook');
-    }else{
-     if(body.includes(prefix)||/role-git-guard\.mjs|runtime-gate\.mjs/.test(body))throw Error('Malformed managed Claude hook command');
-     kept.push(...chunk);
-    }
-    i=j;
-   }
-   lines.splice(pre+1,finish-pre-1,...kept,...entries(skillPath,eol).split(eol));
-  }else lines.splice(end,0,'  PreToolUse:',...entries(skillPath,eol).split(eol));
- }else lines.push('hooks:','  PreToolUse:',...entries(skillPath,eol).split(eol));
- if(requireManaged&&!count)throw Error('Missing managed Claude hook');
- const replacement='---'+eol+lines.join(eol)+eol+'---';
- return replacement+text.slice(fm[0].length);
-}
-export function installClaudeHook(bytes,skillPath){return Buffer.from(update(bytes.toString('utf8'),skillPath,true));}
-export function renderSourceClaudeHook(text){return update(text,'/__ARC_INSTALLED_SKILL__',false);}

package/scripts/probe-runtime-hooks.mjs

@@ -1,55 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import {pathToFileURL} from 'node:url';
-import {summarizeProbe} from '../lib/runtime/capabilities.mjs';
-
-// This tool does not install hooks, grant trust, or execute the tool being probed.
-// Host-result receipts must be supplied by the trusted probe host after checking
-// actual non-execution. A hook-decision receipt alone never verifies denial.
-export function writeProbeReceipt(receipt,data,write = fs.writeFileSync) {
-    let fd;
-    try {
-      fd=fs.openSync(receipt,fs.constants.O_WRONLY|fs.constants.O_CREAT|fs.constants.O_EXCL|fs.constants.O_NOFOLLOW,0o600);
-      write(fd,JSON.stringify(data)+'\n');
-    } catch(error) {
-      if(fd !== undefined) fs.unlinkSync(receipt);
-      throw error;
-    } finally { if(fd !== undefined) fs.closeSync(fd); }
-}
-
-if(process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
-try {
-  const [mode,...args] = process.argv.slice(2);
-  const options = {};
-  for(let i=0;i<args.length;i+=2) {
-    if(!['--platform','--session','--version','--receipt','--attempt','--scratch'].includes(args[i]) || !args[i+1]) throw new Error('Invalid probe options');
-    options[args[i].slice(2)] = args[i+1];
-  }
-  const {platform,session:sessionRef,version:platformVersion,attempt:attemptRef,scratch,receipt} = options;
-  if(!['codex','claude'].includes(platform) || !sessionRef || !platformVersion || !attemptRef || !receipt || !path.isAbsolute(receipt)) throw new Error('Explicit platform, session, version and absolute scratch receipt required');
-  if(mode === 'summary') {
-    const parsed = JSON.parse(fs.readFileSync(receipt,'utf8'));
-    console.log(JSON.stringify(summarizeProbe(Array.isArray(parsed)?parsed:[parsed],{platform,sessionRef,platformVersion,attemptRef})));
-  } else if(mode === 'hook') {
-    const input = JSON.parse(fs.readFileSync(0,'utf8'));
-    if(input.hook_event_name !== 'PreToolUse' || typeof input.tool_name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,79}$/.test(input.tool_name)) throw new Error('Only PreToolUse canary requests supported');
-    if(!scratch || !path.isAbsolute(scratch)) throw new Error('Explicit private scratch directory required');
-    const realScratch=fs.realpathSync(scratch);
-    const stat=fs.lstatSync(scratch);
-    if(stat.isSymbolicLink() || !stat.isDirectory() || (stat.mode & 0o077) !== 0 ||
-      (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
-      path.dirname(realScratch) !== fs.realpathSync(os.tmpdir()) ||
-      !path.basename(realScratch).startsWith('arc-runtime-probe-') ||
-      fs.realpathSync(path.dirname(path.resolve(receipt))) !== realScratch) throw new Error('Receipt must be directly inside private probe scratch');
-    const data={source:'native',kind:'hook-decision',platform,platformVersion,sessionRef,attemptRef,
-      event:'PreToolUse',toolPath:input.tool_name,
-      operation:input.tool_name === 'Agent' ? (platform === 'codex' ? 'spawn_agent' : 'Agent') : null,decision:'deny'};
-    // Exclusive creation prevents truncation and symlink following. No staging
-    // file is needed; remove our own new receipt if its write fails.
-    writeProbeReceipt(receipt,data);
-    console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:'ARC scratch canary deny'}}));
-  } else throw new Error('Expected hook or summary mode');
-} catch(error) { console.error(error.message); process.exitCode=1; }
-
-}

package/scripts/update-superpowers-local.sh

@@ -1,4 +0,0 @@
-#!/bin/sh
-set -eu
-script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-exec node "$script_dir/update-superpowers.mjs" "$@"