ai-install-guard 0.0.0 → 0.2.0

package/hooks/guard/pane.tsx

@@ -0,0 +1,253 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, RenderElement, RenderInput } from 'claude-code'
+
+import type { GuardRow, GuardStatus, GuardView } from '../../types'
+import { GROUPS } from '../scan/checks/types'
+import { locate } from '../scan/verdict'
+import { badgeFor } from './badge'
+import { recordDecision, saveLastView } from './decisions'
+import { needsConfirmation, PANE_ID, primaryLabel } from './view'
+
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
+
+export const REPORT_TEXT = 'last-report-text'
+
+const ICON: Record<GuardStatus, string> = { fail: '✖', warn: '⚠', pass: '✔', info: '·' }
+const COLOR: Record<GuardStatus, string> = { fail: 'error', warn: 'warning', pass: 'success', info: 'subtle' }
+const VERDICT_COLOR = { safe: 'success', caution: 'warning', reject: 'error', unverified: 'warning' } as const
+
+type PaneInput = RenderInput<'Pane'>
+
+/** The pane's tree for the scan in state, or a note when there is none. */
+export async function drawPane($: EngineInterface, e: PaneInput): Promise<RenderElement> {
+  const { Box, Text, Button } = $.ui.resolve(e)
+  const view = await read($, viewAtom)
+  const width = Math.max(20, e.props.bodyColumns)
+
+  if (view === null) {
+    return (
+      <Box flexDirection="column" width={width}>
+        <Text dimColor>No scan yet. Run /guard scan &lt;path&gt;.</Text>
+      </Box>
+    )
+  }
+
+  const header = [
+    view.kind === undefined ? undefined : `A ${view.kind}`,
+    view.sha === undefined ? undefined : `commit ${view.sha.slice(0, 12)}`,
+    view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`,
+  ]
+    .filter(part => part !== undefined)
+    .join(' · ')
+
+  const rowsOf = (group: string): GuardRow[] => view.rows.filter(row => row.group === group)
+  const isOpen = (row: GuardRow): boolean => view.details || view.expanded.includes(row.id)
+  const toggle = (id: string) => () =>
+    update($, viewAtom, current =>
+      current === null ? current : { ...current, expanded: current.expanded.includes(id) ? current.expanded.filter(item => item !== id) : [...current.expanded, id] },
+    )
+  const codeOpen = (row: GuardRow): boolean => (view.codeOpen ?? []).includes(row.id)
+  const toggleCode = (id: string) => () =>
+    update($, viewAtom, current => {
+      if (current === null) return current
+      const open = current.codeOpen ?? []
+      return { ...current, codeOpen: open.includes(id) ? open.filter(item => item !== id) : [...open, id] }
+    })
+
+  const decide = (decision: 'approved' | 'rejected', overridden: boolean) => async () => {
+    const current = await read($, viewAtom)
+    if (current === null || current.verdict === undefined) return
+    // A scan that never read the files has no tree hash to pin a decision to:
+    // the pane closes, nothing is remembered, and nothing claims otherwise.
+    if (current.treeHash === undefined) {
+      $.ui.toast('AI Install Guard: closed; the scan read nothing, so there is no decision to remember')
+      await $.ui.close({ id: PANE_ID })
+      return
+    }
+    const decidedAt = Date.now()
+    try {
+      await recordDecision($, {
+        target: current.target,
+        root: current.root,
+        sha: current.sha,
+        treeHash: current.treeHash,
+        verdict: current.verdict.recommendation,
+        verdictKind: current.verdict.kind,
+        decision,
+        overridden,
+        decidedAt,
+      })
+    } catch {
+      // Nothing was saved: say so, and leave the pane open to try again.
+      $.ui.toast('AI Install Guard: could not save the decision; nothing was recorded')
+      return
+    }
+    const decided = { ...current, decision, decidedAt, confirming: false }
+    await update($, viewAtom, () => decided)
+    // The reopened report shows the outcome, not the buttons again.
+    await saveLastView($, decided).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: ${decision === 'approved' ? 'approved' : 'rejected'} ${current.target}`)
+    await $.ui.close({ id: PANE_ID })
+  }
+
+  const primary = async () => {
+    const current = await read($, viewAtom)
+    if (current === null) return
+    if (needsConfirmation(current)) {
+      await update($, viewAtom, latest => (latest === null ? latest : { ...latest, confirming: true }))
+      return
+    }
+    await decide('approved', false)()
+  }
+
+  const copyBadge = async () => {
+    const made = badgeFor(view)
+    if ('refusal' in made) {
+      $.ui.toast(`AI Install Guard: ${made.refusal}`)
+      return
+    }
+    const result = await $.ui.copy({ text: made.markdown, surface: e.surface })
+    $.ui.toast(result.isCopied ? 'AI Install Guard: badge copied; paste it near the top of your README' : 'AI Install Guard: could not copy the badge here')
+  }
+  const offersBadge = view.treeHash !== undefined && (view.verdict?.kind === 'safe' || view.verdict?.kind === 'caution')
+
+  const copy = async () => {
+    const text = await $.store.get(REPORT_TEXT)
+    const result = await $.ui.copy({ text: typeof text === 'string' ? text : 'No report yet.', surface: e.surface })
+    $.ui.toast(result.isCopied ? 'AI Install Guard: report copied' : 'AI Install Guard: could not copy the report here')
+  }
+
+  const verdict = view.verdict
+  return (
+    <Box flexDirection="column" width={width}>
+      <Text bold wrap="truncate-end">
+        AI Install Guard · {view.target}
+      </Text>
+      {header !== '' && (
+        <Text dimColor wrap="truncate-end">
+          {header}
+        </Text>
+      )}
+
+      {verdict === undefined ? (
+        <Text color="suggestion" wrap="truncate-end">
+          Scanning: {view.stage}…
+        </Text>
+      ) : (
+        <Box key="verdict" flexDirection="column" borderStyle="round" borderColor={VERDICT_COLOR[verdict.kind]} paddingX={1} marginTop={1}>
+          <Text bold color={VERDICT_COLOR[verdict.kind]}>
+            {verdict.recommendation}
+          </Text>
+          {verdict.reasons.map(reason => (
+            <Text wrap="truncate-end">
+              {reason}
+            </Text>
+          ))}
+        </Box>
+      )}
+
+      {verdict !== undefined && (
+        <Text>
+          {verdict.counts.pass} passed · {verdict.counts.warn} warning{verdict.counts.warn === 1 ? '' : 's'} · {verdict.counts.fail} failed
+        </Text>
+      )}
+      {verdict !== undefined && view.rows.length > 0 && (
+        <Text dimColor wrap="truncate-end">
+          Quoted text comes from the scanned files and is untrusted.
+        </Text>
+      )}
+
+      {GROUPS.filter(group => rowsOf(group.id).length > 0).map(group => (
+        <Box key={`group-${group.id}`} flexDirection="column" marginTop={1}>
+          <Text bold>{group.title}</Text>
+          {rowsOf(group.id).map(row => {
+            const first = row.evidence[0]
+            const headline = row.summary?.[0]
+            const summary = headline !== undefined ? `: ${headline}` : first === undefined ? '' : `: ${locate(first.file, first.line)}${first.excerpt}`
+            const places = row.evidence.length + row.more
+            // With a summary, the code lines are one step further in.
+            const showCode = row.summary === undefined || codeOpen(row)
+            return (
+              <Box key={`row-${row.id}`} flexDirection="column">
+                <Button key={`toggle-${row.id}`} plain onPress={toggle(row.id)}>
+                  <Text color={COLOR[row.status]}>{ICON[row.status]}</Text> {row.title}
+                  <Text dimColor>{truncate(summary, width - row.title.length - 4)}</Text>
+                </Button>
+                {isOpen(row) && (
+                  <Box key={`detail-${row.id}`} flexDirection="column" paddingLeft={2}>
+                    {row.summary?.map((line, index) => (
+                      <Text wrap="wrap" bold={index === 0}>
+                        {line}
+                      </Text>
+                    ))}
+                    {(row.status === 'fail' || row.status === 'warn') && (
+                      <Text dimColor wrap="wrap">
+                        {row.advice}
+                      </Text>
+                    )}
+                    {row.summary !== undefined && places > 0 && (
+                      <Button key={`code-${row.id}`} plain onPress={toggleCode(row.id)}>
+                        <Text color="suggestion">
+                          {codeOpen(row) ? 'Hide the code' : `Show the code (${places} place${places === 1 ? '' : 's'})`}
+                        </Text>
+                      </Button>
+                    )}
+                    {showCode &&
+                      row.evidence.map(item => (
+                        <Text wrap="wrap" color={item.status === undefined ? undefined : COLOR[item.status]}>
+                          {locate(item.file, item.line)}
+                          {item.excerpt}
+                        </Text>
+                      ))}
+                    {showCode && row.more > 0 && <Text dimColor>… and {row.more} more in the copied report</Text>}
+                  </Box>
+                )}
+              </Box>
+            )
+          })}
+        </Box>
+      ))}
+
+      {verdict !== undefined && view.decision === undefined && !view.confirming && (
+        <Box key="actions" flexDirection="row" gap={1} marginTop={1}>
+          {view.treeHash !== undefined && (
+            <Button key="install" label={primaryLabel(view)} hotkey="i" variant={needsConfirmation(view) ? 'secondary' : 'primary'} onPress={primary} />
+          )}
+          <Button key="reject" label="Reject" hotkey="r" variant={needsConfirmation(view) ? 'primary' : 'secondary'} onPress={decide('rejected', false)} />
+          <Button key="details" label={view.details ? 'Fewer details' : 'Details'} hotkey="d" onPress={() => update($, viewAtom, current => (current === null ? current : { ...current, details: !current.details }))} />
+          <Button key="copy" label="Copy report" hotkey="c" onPress={copy} />
+          {offersBadge && <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />}
+        </Box>
+      )}
+
+      {verdict !== undefined && view.confirming && (
+        <Box key="confirm-row" flexDirection="column" marginTop={1}>
+          <Text color="warning" wrap="wrap">
+            The verdict is {verdict.recommendation}. {primaryLabel(view)}?
+          </Text>
+          <Box flexDirection="row" gap={1}>
+            <Button key="confirm" label={`Yes, ${primaryLabel(view).toLowerCase()}`} hotkey="y" onPress={decide('approved', true)} />
+            <Button key="cancel" label="Cancel" hotkey="n" variant="primary" onPress={() => update($, viewAtom, current => (current === null ? current : { ...current, confirming: false }))} />
+          </Box>
+        </Box>
+      )}
+
+      {view.decision !== undefined && (
+        <Text color={view.decision === 'approved' ? 'success' : 'error'}>
+          {view.decision === 'approved' ? 'Approved' : 'Rejected'}
+          {view.decidedAt === undefined ? '' : ` on ${new Date(view.decidedAt).toISOString().slice(0, 10)}`}. The decision is saved for this exact version; /guard forget clears it.
+        </Text>
+      )}
+      {view.decision !== undefined && offersBadge && (
+        <Box key="after-decision" flexDirection="row" gap={1} marginTop={1}>
+          <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />
+        </Box>
+      )}
+    </Box>
+  )
+}
+
+function truncate(text: string, room: number): string {
+  if (room <= 1) return ''
+  return text.length <= room ? text : `${text.slice(0, Math.max(0, room - 1))}…`
+}

package/hooks/guard/view.ts

@@ -0,0 +1,87 @@
+import type { GuardAction, GuardRow, GuardView } from '../../types'
+import { redactSecrets } from '../scan/checks/patterns'
+import type { CheckResult } from '../scan/checks/types'
+import { safeLine } from '../scan/safe-text'
+import type { ScanReport } from '../scan/scan'
+
+/** Evidence the pane keeps per row; the full list stays in the stored report. */
+const EVIDENCE_PER_ROW = 20
+/** Characters the pane keeps per excerpt or reason: one huge hook command cannot fill the store. */
+const MAX_TEXT = 500
+
+function clip(text: string): string {
+  return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}…` : text
+}
+
+export const PANE_ID = 'ai-install-guard'
+
+export function scanningView(target: string, action: GuardAction): GuardView {
+  return { target: safeLine(target), action, stage: 'Starting', rows: [], expanded: [], details: false, confirming: false }
+}
+
+/** The pane's view of a finished scan: compact, every quoted text made safe. */
+export function viewOf(report: ScanReport, action: GuardAction): GuardView {
+  return {
+    // The person's own words, but drawn beside an Approve button: made safe too.
+    target: safeLine(report.target),
+    action,
+    stage: '',
+    verdict: {
+      ...report.verdict,
+      reasons: report.verdict.reasons.map(reason => clip(safeLine(redactSecrets(reason)))),
+    },
+    rows: report.results.map(rowOf),
+    kind: report.kind,
+    // A remote scan's folder is a temporary one: its source names it instead.
+    root:
+      report.source !== undefined
+        ? safeLine(`${report.source.url}${report.source.subdir === undefined ? '' : `#${report.source.subdir}`}`)
+        : report.inventory === undefined
+          ? undefined
+          : safeLine(report.inventory.root),
+    sha: report.source?.sha,
+    ...(report.source?.subdir === undefined ? {} : { subdir: encodeFolder(report.source.subdir) }),
+    treeHash: report.inventory?.treeHash,
+    expanded: [],
+    details: false,
+    confirming: false,
+  }
+}
+
+function rowOf(result: CheckResult): GuardRow {
+  return {
+    id: result.id,
+    group: result.group,
+    title: result.title,
+    status: result.status,
+    evidence: result.evidence.slice(0, EVIDENCE_PER_ROW).map(item => ({
+      file: clip(safeLine(redactSecrets(item.file))),
+      line: item.line,
+      excerpt: clip(safeLine(redactSecrets(item.excerpt))),
+      status: item.status,
+    })),
+    more: Math.max(0, result.evidence.length - EVIDENCE_PER_ROW),
+    advice: result.advice,
+    ...(result.summary === undefined || result.summary.length === 0 ? {} : { summary: result.summary.slice(0, 8).map(line => clip(safeLine(redactSecrets(line)))) }),
+  }
+}
+
+/** Whether the primary button needs a second, explicit confirmation: the verdict is Do not install or Could not verify. */
+export function needsConfirmation(view: GuardView): boolean {
+  return view.verdict === undefined || view.verdict.kind === 'reject' || view.verdict.kind === 'unverified'
+}
+
+/** The primary button's label for this verdict. */
+export function primaryLabel(view: GuardView): string {
+  const verb = view.action === 'install' ? 'Install' : 'Approve'
+  return needsConfirmation(view) ? `${verb} anyway` : verb
+}
+
+/**
+ * A folder name as the pane and a badge show it: whole characters other than
+ * letters, digits and `_ . / -` percent-encoded, so the exact folder stays
+ * named and nothing in it can be read as markup or hide itself.
+ */
+export function encodeFolder(folder: string): string {
+  return folder.replace(/[^\w./-]/gu, char => [...new TextEncoder().encode(char)].map(byte => `%${byte.toString(16).toUpperCase().padStart(2, '0')}`).join(''))
+}

package/hooks/mod-host.ts

@@ -27,5 +27,6 @@ export function modHost($: EngineInterface): Host {
       throw new Error(`could not read the link ${path}`)
     },
     run: (argv, options) => $.process.run(argv, options),
+    fetch: (url, init) => $.http.fetch(url, init),
   }
 }

package/hooks/register.tsx

@@ -1,49 +1,199 @@
-import type { Register } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+import { atom, update } from 'claude-code'
 
+import { badgeFor } from './guard/badge'
+import { decisionFor, forgetDecisions, loadDecisions, loadLastView, MAX_REPORT_CHARS, saveLastView } from './guard/decisions'
+import { drawPane, REPORT_TEXT } from './guard/pane'
+import { PANE_ID, scanningView, viewOf } from './guard/view'
 import { modHost } from './mod-host'
 import type { Host } from './scan/host'
-import { takeInventory } from './scan/inventory'
-import { formatInventory } from './scan/report'
+import { looksRemote, parseRemote, type RemoteSpec } from './scan/remote'
+import { formatReport } from './scan/report'
 import { safeLine } from './scan/safe-text'
+import { scanFolder, scanRemote } from './scan/scan'
+
+// Claude Code reads every state reference from the file that uses it, so each
+// module declares its own atom for the pane's view.
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
 
 const USAGE = [
   'Usage:',
-  '  /guard scan <path>   Scan a local plugin, mod or skill folder without installing it',
+  '  /guard scan <path>            Scan a local plugin, mod or skill folder without installing it',
+  '  /guard scan <repository>      Fetch one commit of a repository and scan it: https://host/owner/repo,',
+  '                                github:owner/repo or owner/repo, with an optional @ref',
+  '      --ref <branch|tag|commit>   The commit to scan (the default branch otherwise)',
+  '      --path <folder>             A folder inside the repository',
+  '      --details                   The full report as text',
+  '  /guard report                 Reopen the last report',
+  '  /guard badge                  A README badge for the last scan (Safe to install or Review what it can do)',
+  '  /guard list                   Your approved and rejected versions',
+  '  /guard forget <name>          Forget decisions about a name, so it is judged again',
 ].join('\n')
 
-export const register: Register = on => {
+export const register: Register = (on, options) => {
+  // Off unless you turn it on: the lookups send package and plugin names out.
+  const lookups = options.outsideLookups === true
+
   on('session.start', async ($, e, next) => {
     await $.command.register({
       name: 'guard',
       description: 'Scan a plugin, mod, skill or MCP server without installing it',
-      argumentHint: 'scan <path>',
+      argumentHint: 'scan <path | repository> | report | badge | list | forget <name>',
     })
     return next(e)
   })
 
   on('command.run', { command: 'guard' }, async ($, e) => {
-    const { sub, rest } = splitArgs(e.args)
-    if (sub !== 'scan' || rest === '') {
-      return { text: USAGE }
-    }
-    const host = modHost($)
-    try {
-      const tree = await takeInventory(host, await expandHome(host, rest))
-      return { text: formatInventory(rest, tree.inventory) }
-    } catch (error) {
-      return { text: `Could not verify ${safeLine(rest)}: ${safeLine(reasonOf(error))}` }
+    const { sub, rest, details, ref, path, error } = splitArgs(e.args)
+    if (error !== undefined) return { text: `AI Install Guard: ${error}\n\n${USAGE}` }
+    if (sub === 'scan' && rest !== '') return { text: await scan($, rest, details, { ref, path }, lookups) }
+    if (sub === 'report') return { text: await reopen($) }
+    if (sub === 'badge') return { text: await badge($) }
+    if (sub === 'list') return { text: await list($) }
+    if (sub === 'forget' && rest !== '') {
+      const count = (await forgetDecisions($, rest)).length
+      return { text: `AI Install Guard: forgot ${count} decision${count === 1 ? '' : 's'} about ${safeLine(rest)}.` }
     }
+    return { text: USAGE }
   }).catch(() => ({ text: 'AI Install Guard: the command failed before it could answer.' }))
+
+  on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e) => drawPane($, e))
+}
+
+/**
+ * Scans a folder with the pane showing progress and then the verdict. The
+ * command's own answer, which the model also reads, is one line: the quoted
+ * findings stay in the pane. Where no pane can show (a headless run), or with
+ * --details, the answer is the full text report.
+ */
+async function scan($: EngineInterface, target: string, details: boolean, flags: { ref?: string; path?: string }, lookups: boolean): Promise<string> {
+  const host = modHost($)
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  // Until this scan's report is stored, Copy report has nothing to copy, never
+  // the previous scan's report.
+  await $.store.delete(REPORT_TEXT).catch(() => undefined)
+  await update($, viewAtom, () => scanningView(target, 'approve'))
+  $.ui.status(`AI Install Guard: scanning ${safeLine(target)}`)
+  try {
+    const options = {
+      lookups,
+      // Stage names can carry a candidate's own words (a plugin's name).
+      onStage: (stage: string) => update($, viewAtom, current => (current === null ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
+    }
+    const spec = await remoteSpecFor(host, target, flags)
+    const report = spec === undefined ? await scanFolder(host, target, await expandHome(host, target), options) : await scanRemote(host, target, spec, options)
+    // A tree you already decided on shows that decision, not the buttons
+    // again, unless it now judges worse than when you approved it.
+    const earlier = report.inventory === undefined ? undefined : await decisionFor($, { treeHash: report.inventory.treeHash, sha: report.source?.sha }, report.verdict.kind).catch(() => undefined)
+    const view = earlier === undefined ? viewOf(report, 'approve') : { ...viewOf(report, 'approve'), decision: earlier.decision, decidedAt: earlier.decidedAt }
+    const text = formatReport(report, { details: true })
+    // The report text is stored before the pane shows the verdict, so Copy
+    // report always copies this scan's report. It is held well inside the
+    // store's limit; a failed write leaves Copy with nothing, not old text.
+    const stored = text.length > MAX_REPORT_CHARS ? `${text.slice(0, MAX_REPORT_CHARS)}\n… the report was cut here to fit the store` : text
+    await $.store.set(REPORT_TEXT, stored).catch(() => undefined)
+    await update($, viewAtom, () => view)
+    await saveLastView($, view).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}`)
+    // Where no pane shows, the answer is the whole report: findings and advice.
+    if (!opened.isPlaced || details) return text
+    return `AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}. The report is in the pane; /guard report reopens it.`
+  } catch (error) {
+    const reason = `Could not verify ${safeLine(target)}: ${safeLine(reasonOf(error))}`
+    await $.store.set(REPORT_TEXT, reason).catch(() => undefined)
+    // The pane, and the report /guard report reopens, show this failure: never
+    // a scanning pane, and never an older verdict in its place.
+    const failed = { ...scanningView(target, 'approve'), stage: '', verdict: { kind: 'unverified' as const, recommendation: 'Could not verify', reasons: [reason], counts: { pass: 0, warn: 0, fail: 0, info: 0 } } }
+    await update($, viewAtom, () => failed).catch(() => undefined)
+    await saveLastView($, failed).catch(() => undefined)
+    return reason
+  } finally {
+    $.ui.status(undefined)
+  }
+}
+
+async function reopen($: EngineInterface): Promise<string> {
+  const view = await loadLastView($)
+  if (view === undefined) return 'AI Install Guard: no report yet. Run /guard scan <path>.'
+  await update($, viewAtom, () => ({ ...view, confirming: false }))
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  if (opened.isPlaced) return `AI Install Guard: reopened the report for ${safeLine(view.target)}.`
+  const text = await $.store.get(REPORT_TEXT)
+  return typeof text === 'string' ? text : 'AI Install Guard: the last report is no longer stored.'
+}
+
+async function badge($: EngineInterface): Promise<string> {
+  const view = await loadLastView($)
+  const made = badgeFor(view)
+  if ('refusal' in made) return `AI Install Guard: ${made.refusal}`
+  return [
+    `AI Install Guard: a README badge for ${view?.target ?? 'the last scan'} at ${made.pin}. Paste it near the top of your README:`,
+    '',
+    made.markdown,
+    '',
+    'It names the exact version that was scanned. A change to your code needs a new scan and a new badge; the guard checks a badge against its own scan and never trusts it.',
+  ].join('\n')
+}
+
+async function list($: EngineInterface): Promise<string> {
+  const decisions = await loadDecisions($)
+  if (decisions.length === 0) return 'AI Install Guard: no decisions yet.'
+  const lines = decisions.map(item => {
+    const when = new Date(item.decidedAt).toISOString().slice(0, 10)
+    const how = item.decision === 'approved' ? (item.overridden ? 'approved against the verdict' : 'approved') : 'rejected'
+    return `  ${when}  ${how.padEnd(28)} ${safeLine(item.target)}  (${item.verdict}, tree ${item.treeHash.slice(7, 19)})`
+  })
+  return ['AI Install Guard: your decisions, newest first', ...lines].join('\n')
 }
 
-/** `scan "my folder"` → `{ sub: 'scan', rest: 'my folder' }`. */
-export function splitArgs(args: string): { sub: string; rest: string } {
+/**
+ * `scan --details --ref v1 "my folder"` → `{ sub: 'scan', details: true, ref: 'v1', rest: 'my folder' }`.
+ * Options count only as their own tokens right after the subcommand, so a
+ * quoted path that contains one is left whole.
+ */
+export function splitArgs(args: string): { sub: string; rest: string; details: boolean; ref?: string; path?: string; error?: string } {
   const trimmed = args.trim()
   const space = trimmed.search(/\s/)
   const sub = space === -1 ? trimmed : trimmed.slice(0, space)
-  const rest = space === -1 ? '' : trimmed.slice(space).trim()
-  const unquoted = /^(["']).*\1$/.test(rest) ? rest.slice(1, -1) : rest
-  return { sub: sub.toLowerCase(), rest: unquoted }
+  let rest = space === -1 ? '' : trimmed.slice(space).trim()
+  let details = false
+  let ref: string | undefined
+  let path: string | undefined
+  for (;;) {
+    const option = /^(--details|--ref|--path)(?:\s+|$)/.exec(rest)
+    if (option === null) break
+    rest = rest.slice(option[0].length)
+    if (option[1] === '--details') {
+      details = true
+      continue
+    }
+    const value = /^("[^"]*"|'[^']*'|\S+)\s*/.exec(rest)
+    if (value === null || (value[1] as string).startsWith('--')) return { sub: sub.toLowerCase(), rest: '', details, error: `${option[1]} needs a value` }
+    rest = rest.slice(value[0].length)
+    if (option[1] === '--ref') ref = unquote(value[1] as string)
+    else path = unquote(value[1] as string)
+  }
+  return { sub: sub.toLowerCase(), rest: unquote(rest), details, ref, path }
+}
+
+/**
+ * The remote source `target` names, or undefined for a local folder. A bare
+ * owner/repo is a folder when one exists by that name and no --ref or --path
+ * says otherwise.
+ */
+async function remoteSpecFor(host: Host, target: string, flags: { ref?: string; path?: string }): Promise<RemoteSpec | undefined> {
+  const shape = looksRemote(target)
+  const asked = flags.ref !== undefined || flags.path !== undefined
+  if (shape === 'local') {
+    if (asked) throw new Error('--ref and --path apply to a repository, not to a folder')
+    return undefined
+  }
+  if (shape === 'maybe' && !asked && (await host.stat(target).catch(() => undefined)) !== undefined) return undefined
+  return parseRemote(target, { ref: flags.ref, subdir: flags.path })
+}
+
+function unquote(text: string): string {
+  return /^(["']).*\1$/.test(text) ? text.slice(1, -1) : text
 }
 
 async function expandHome(host: Host, path: string): Promise<string> {