@davait/aipictury 1.9.2

package/ext/paths.js

@@ -0,0 +1,50 @@
+'use strict'
+// Where the agent may work: inside the workspace folder, and nowhere else.
+
+const vscode = require('vscode')
+const path = require('path')
+
+/** The workspace folder everything is resolved against: the one holding the file the
+ *  user is working in, when several are open (a multi-root workspace), else the first. */
+function root() {
+  const folders = vscode.workspace.workspaceFolders
+  if (!folders || !folders.length) throw new Error('no folder is open in this window')
+  const active = vscode.window.activeTextEditor?.document?.uri
+  const holding = active && vscode.workspace.getWorkspaceFolder(active)
+  return (holding || folders[0]).uri
+}
+
+// More folders the agent may work in, besides the workspace (the CLI's --add-dir): absolute.
+const extra = []
+function addRoots(dirs) {
+  for (const d of dirs || []) {
+    const abs = path.resolve(String(d))
+    if (!extra.includes(abs)) extra.push(abs)
+  }
+}
+const underExtra = (abs) => extra.find((r) => abs === r || abs.startsWith(r + path.sep))
+
+/** Resolves a path from the model, refusing anything outside the workspace (and the folders
+ *  added with --add-dir). The model is not malicious, but it is wrong often enough to matter. */
+function resolve(relative) {
+  const base = root()
+  let given = String(relative || '.').trim()
+  // An added folder is named by its absolute path (the model is told which ones there are).
+  if (path.isAbsolute(given) && underExtra(path.resolve(given))) return vscode.Uri.file(path.resolve(given))
+  // A model often hands back the absolute path it was shown: inside the workspace, fine.
+  if (given.startsWith(`${base.fsPath}${path.sep}`) || given === base.fsPath) given = path.relative(base.fsPath, given) || '.'
+  // Any other absolute path is refused rather than quietly read as a relative one: the
+  // model asking for /etc/passwd should be told no, not handed <workspace>/etc/passwd.
+  if (given.startsWith('/') || given.startsWith('\\') || /^[a-zA-Z]:[/\\]/.test(given)) {
+    throw new Error(`${given} is an absolute path outside the workspace; use a path relative to the workspace root`)
+  }
+  const target = vscode.Uri.joinPath(base, given)
+  const inside = target.fsPath === base.fsPath || target.fsPath.startsWith(base.fsPath + path.sep)
+  if (!inside) throw new Error(`${relative} is outside the workspace`)
+  return target
+}
+
+/** A path as the model and the user see it: relative to the root (absolute in an added folder). */
+const rel = (uri) => (underExtra(uri.fsPath) ? uri.fsPath : path.relative(root().fsPath, uri.fsPath) || '.')
+
+module.exports = { root, resolve, rel, addRoots, extraRoots: () => [...extra] }

package/ext/permissions.js

@@ -0,0 +1,229 @@
+'use strict'
+// Permission rules — allow, ask, deny — in Claude Code's syntax, from the settings files
+// (prefs.js: yours, the project's, your local one, and Claude Code's own, read-only):
+//
+//   Bash                     every command          Read(./.env)        one file (read tools)
+//   Bash(npm run test:*)     a command and its args Edit(src/**)        files the agent may change
+//   Bash(git commit *)       a glob                 WebFetch(domain:github.com)
+//   WebSearch                                       mcp__github, mcp__github__create_issue
+//   Browser(domain:github.com)  what the browser may open and act on
+//
+// Our own tool names work too (run_command(npm test), read_file(docs/**)). Deny beats ask
+// beats allow. A command with several parts (a && b, a | b, a; b) is allowed only when every
+// part is, and denied or asked when any part is — "git status && rm -rf x" is not "git status".
+// No VS Code here: the rules are checked the same way in tests and, later, in the CLI.
+const os = require('os')
+const path = require('path')
+const prefs = require('./prefs')
+
+// Which family a tool belongs to, and what its rule's (…) is matched against.
+const FAMILY = {
+  run_command: 'Bash', monitor: 'Bash', powershell: 'PowerShell',
+  read_file: 'Read', list_files: 'Read', grep: 'Read', glob: 'Read', search: 'Read', code_intel: 'Read',
+  write_file: 'Edit', edit_file: 'Edit', notebook_edit: 'Edit',
+  fetch_url: 'WebFetch', web_search: 'WebSearch', task: 'Task', generate_media: 'Media', browser: 'Browser',
+}
+// Names a rule may use for a family: Claude Code's and ours.
+const ALIASES = {
+  Bash: ['Bash', 'run_command'],
+  PowerShell: ['PowerShell', 'powershell'],
+  Read: ['Read', 'Grep', 'Glob', 'LS', 'read_file', 'list_files', 'grep', 'glob', 'search', 'code_intel'],
+  Edit: ['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'write_file', 'edit_file', 'notebook_edit'],
+  WebFetch: ['WebFetch', 'fetch_url'],
+  WebSearch: ['WebSearch', 'web_search'],
+  Task: ['Task', 'task'],
+  Media: ['Media', 'generate_media'],
+  Browser: ['Browser', 'browser'],
+}
+
+/** "Bash(npm run test:*)" → { tool: 'Bash', spec: 'npm run test:*' }; a bare name has no spec. */
+function parseRule(text) {
+  const m = /^\s*([\w.*-]+)\s*(?:\(([\s\S]*)\))?\s*$/.exec(String(text || ''))
+  if (!m) return null
+  return { tool: m[1], spec: m[2] === undefined ? null : m[2].trim() }
+}
+
+/** A glob as a regular expression: ** any path, * within a segment, ? one character, {a,b}. */
+function globToRegExp(glob, { anyChar = false } = {}) {
+  let out = ''
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i]
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i += 1
+        if (glob[i + 1] === '/') { i += 1; out += '(?:.*/)?' } else out += '.*'
+      } else out += anyChar ? '.*' : '[^/]*'
+    } else if (c === '?') out += anyChar ? '.' : '[^/]'
+    else if (c === '{') {
+      const end = glob.indexOf('}', i)
+      if (end < 0) { out += '\\{'; continue }
+      out += `(?:${glob.slice(i + 1, end).split(',').map((p) => p.replace(/[.+^$()|[\]\\]/g, '\\$&')).join('|')})`
+      i = end
+    } else out += c.replace(/[.+^$()|[\]\\{}]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+/** The parts of a shell command that run on their own: split at &&, ||, ;, | and new lines,
+ *  outside quotes. `$( … )` and backticks count as a part too. */
+function commandParts(command) {
+  const text = String(command || '')
+  const parts = []
+  let cur = ''
+  let quote = null
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i]
+    if (quote) {
+      if (c === quote) quote = null
+      else if (c === '\\' && quote === '"') { cur += c + (text[i + 1] || ''); i += 1; continue }
+      cur += c
+      continue
+    }
+    if (c === "'" || c === '"') { quote = c; cur += c; continue }
+    if (c === '\\') { cur += c + (text[i + 1] || ''); i += 1; continue }
+    const two = text.slice(i, i + 2)
+    if (two === '&&' || two === '||') { parts.push(cur); cur = ''; i += 1; continue }
+    // & runs in the background — unless it is part of a redirection (2>&1, &>file, <&3).
+    const redirect = c === '&' && (text[i - 1] === '>' || text[i - 1] === '<' || text[i + 1] === '>')
+    if (c === ';' || c === '|' || c === '\n' || (c === '&' && !redirect)) { parts.push(cur); cur = ''; continue }
+    cur += c
+  }
+  parts.push(cur)
+  // Substitutions run too: what is inside $( ) and ` ` is judged as a command of its own.
+  const inner = []
+  for (const m of text.matchAll(/\$\(([^()]*)\)|`([^`]*)`/g)) inner.push(m[1] ?? m[2])
+  return [...parts, ...inner.flatMap((c) => commandParts(c))]
+    .map((p) => p.trim().replace(/\s+/g, ' ')).filter(Boolean)
+}
+
+/** Does a Bash rule's (…) cover one command? "x:*" is x and anything after it; a * is a glob. */
+function commandMatches(spec, command) {
+  const want = spec.trim().replace(/\s+/g, ' ')
+  if (want.endsWith(':*')) {
+    const prefix = want.slice(0, -2).trim()
+    return command === prefix || command.startsWith(`${prefix} `)
+  }
+  if (want.includes('*')) return globToRegExp(want, { anyChar: true }).test(command)
+  return command === want
+}
+
+/** Where a path rule points: //abs, ~/home, and anything else from the workspace root. */
+function rulePath(spec, root) {
+  if (spec.startsWith('//')) return spec.slice(1)
+  if (spec === '~' || spec.startsWith('~/')) return path.join(os.homedir(), spec.slice(1))
+  return path.join(root || '/', spec.replace(/^\.?\//, ''))
+}
+
+function pathMatches(spec, file, root) {
+  const target = path.resolve(root || '/', file || '.')
+  const pattern = rulePath(spec, root)
+  if (!/[*?{]/.test(pattern)) return target === path.resolve(pattern) || target.startsWith(`${path.resolve(pattern)}${path.sep}`)
+  // dir/** is the folder too: grep or list on it reads what is inside.
+  if (pattern.endsWith(`${path.sep}**`) && target === path.resolve(pattern.slice(0, -3))) return true
+  return globToRegExp(pattern).test(target)
+}
+
+function hostOf(url) { try { return new URL(url).hostname.toLowerCase() } catch { return '' } }
+
+/** What a call is, for the rules: its family and what the (…) is matched against. */
+function subjectOf(name, args = {}) {
+  const family = String(name).startsWith('mcp__') ? 'mcp' : FAMILY[name] || name
+  switch (family) {
+    case 'Bash': case 'PowerShell': return { family, commands: commandParts(args.command) }
+    case 'Read': return { family, file: args.path || args.pattern_path || '.' }
+    case 'Edit': return { family, file: args.path }
+    case 'WebFetch': return { family, host: hostOf(args.url) }
+    case 'Browser': return { family, host: hostOf(args.page || args.url) }      // the site it goes to, or acts on
+    case 'Media': return { family, file: args.save_to }
+    case 'Task': return { family, value: args.subagent_type || 'explore' }
+    default: return { family, value: null }
+  }
+}
+
+/** Does one rule cover one call (for Bash: one part of the command)? */
+function covers(rule, name, subject, root, command) {
+  if (!rule) return false
+  if (subject.family === 'mcp') {
+    const tool = rule.tool
+    return !rule.spec && tool.startsWith('mcp__')
+      && (name === tool || name.startsWith(`${tool.replace(/__\*$/, '')}__`))
+  }
+  const names = ALIASES[subject.family] || [subject.family]
+  if (!names.includes(rule.tool)) return false
+  if (rule.spec === null || rule.spec === '' || rule.spec === '*') return true
+  switch (subject.family) {
+    case 'Bash': case 'PowerShell': return commandMatches(rule.spec, command)
+    case 'Read': case 'Edit': case 'Media': return !!subject.file && pathMatches(rule.spec, subject.file, root)
+    case 'WebFetch': case 'Browser': {
+      const domain = rule.spec.replace(/^domain:/, '').toLowerCase()
+      return !!subject.host && (subject.host === domain || subject.host.endsWith(`.${domain}`))
+    }
+    default: return subject.value !== null && rule.spec === subject.value
+  }
+}
+
+/**
+ * The rules' say on a call: { decision: 'deny' | 'ask' | 'allow' | null, rule, level, file }.
+ * null: no rule speaks of it, and the mode decides. `rules` defaults to the settings files.
+ */
+function decide(name, args, { folder, rules, extraAllow, extraDeny } = {}) {
+  let list = rules || prefs.load(folder).merged.permissions
+  // This run's own denials (the CLI's --disallowedTools): above every allow.
+  if (extraDeny?.length) list = { ...list, deny: [...(list.deny || []), ...extraDeny.map((rule) => ({ rule, level: 'session', file: '(--disallowedTools)' }))] }
+  // A slash command's allowed-tools, while it runs: allow rules on top of the files' (never above a deny).
+  if (extraAllow?.length) list = { ...list, allow: [...(list.allow || []), ...extraAllow.map((rule) => ({ rule, level: 'command', file: '(the command\'s allowed-tools)' }))] }
+  const subject = subjectOf(name, args)
+  const parsed = (kind) => (list[kind] || []).map((r) => ({ ...r, parsed: parseRule(typeof r === 'string' ? r : r.rule),
+    rule: typeof r === 'string' ? r : r.rule }))
+  const hit = (kind, command) => parsed(kind).find((r) => covers(r.parsed, name, subject, folder, command))
+  const say = (decision, r) => ({ decision, rule: r.rule, level: r.level, file: r.file })
+  if (subject.family === 'Bash' || subject.family === 'PowerShell') {
+    const parts = subject.commands.length ? subject.commands : ['']
+    for (const kind of ['deny', 'ask']) {
+      for (const part of parts) { const r = hit(kind, part); if (r) return say(kind, r) }
+    }
+    const allowed = parts.map((part) => hit('allow', part))
+    if (allowed.every(Boolean)) return say('allow', allowed[0])
+    return { decision: null }
+  }
+  for (const kind of ['deny', 'ask', 'allow']) {
+    const r = hit(kind)
+    if (r) return say(kind, r)
+  }
+  return { decision: null }
+}
+
+/** The rule a standing yes saves: the command's prefix, the MCP tool, or the tool itself. */
+function ruleFor(name, args, prefix) {
+  if (FAMILY[name] === 'Bash' || FAMILY[name] === 'PowerShell') return `${FAMILY[name]}(${prefix || String(args.command || '').trim()}:*)`
+  if (String(name).startsWith('mcp__')) return name
+  if (FAMILY[name] === 'WebFetch') return `WebFetch(domain:${hostOf(args.url)})`
+  if (FAMILY[name] === 'Browser') return `Browser(domain:${hostOf(args.page || args.url)})`
+  return FAMILY[name] || name
+}
+
+/** Where a standing yes can go: this conversation, or a settings file. */
+const DESTINATIONS = [
+  { id: 'conversation', label: 'in this conversation' },
+  { id: 'local', label: 'in this project, just for you' },
+  { id: 'project', label: 'in this project, for everyone' },
+  { id: 'user', label: 'everywhere, just for you' },
+]
+
+/** Saves a standing yes in a settings file (never Claude Code's). Returns the file. */
+function remember(folder, destination, rule) {
+  if (destination === 'conversation') return null
+  return prefs.addRule(folder, destination, 'allow', rule)
+}
+
+/** The tools a bare rule names ("Bash", "Edit", "WebFetch", an mcp__ tool): what a run without them is not offered. */
+function toolsNamed(rule) {
+  const r = parseRule(rule)
+  if (r.spec) return []
+  const family = Object.entries(ALIASES).find(([, names]) => names.includes(r.tool))?.[0]
+  if (!family) return [r.tool]
+  return Object.entries(FAMILY).filter(([, f]) => f === family).map(([tool]) => tool)
+}
+
+module.exports = { toolsNamed, parseRule, globToRegExp, commandParts, commandMatches, pathMatches, subjectOf, decide, ruleFor,
+  remember, DESTINATIONS, FAMILY }

package/ext/plans.js

@@ -0,0 +1,110 @@
+'use strict'
+// The plan as a document, as in Claude Code: when the agent presents a plan, it can be opened
+// as a Markdown file (kept in ~/.aipictury/plans/<project>/, never in the workspace), edited,
+// and commented on line by line with VS Code's comments. "Revise" sends the comments — each
+// with the line it is on — and any edits back to the agent; "Approve" chooses the mode to
+// carry it out in, with the plan as edited.
+const fs = require('fs')
+const path = require('path')
+const vscode = require('vscode')
+const { home, projectKey } = require('./sessions')
+
+const MODES = [
+  { id: 'edits', label: 'Approve — and edit automatically', detail: 'File changes go ahead; commands are asked' },
+  { id: 'ask', label: 'Approve — and ask before each change', detail: 'Manual mode' },
+  { id: 'never', label: 'Approve — in Auto mode', detail: 'Routine work goes ahead; anything risky is asked' },
+]
+
+function planFile(folder, id) {
+  return path.join(home(), 'plans', projectKey(folder || 'no-folder'), `${String(id).replace(/[^\w-]/g, '')}.md`)
+}
+
+function register(context, registry) {
+  const controller = vscode.comments.createCommentController('aipictury.plan', 'Plan comments')
+  controller.options = { prompt: 'Comment on this part of the plan…', placeHolder: 'What should change here?' }
+  const threads = new Map()          // plan file → its comment threads
+  context.subscriptions.push(controller)
+
+  /** The panel whose pending plan is this file. */
+  const owner = (file) => registry.all().find((p) => p.pendingPlan?.file === file)
+  controller.commentingRangeProvider = {
+    provideCommentingRanges: (doc) => (owner(doc.uri.fsPath) ? [new vscode.Range(0, 0, Math.max(0, doc.lineCount - 1), 0)] : []),
+  }
+
+  /** Adds a comment at a line (the gutter's "+", or a test). */
+  function addNote(uri, line, text, thread) {
+    const t = thread || controller.createCommentThread(uri, new vscode.Range(line, 0, line, 0), [])
+    t.comments = [...t.comments, { body: new vscode.MarkdownString(String(text)), mode: vscode.CommentMode.Preview,
+      author: { name: 'You' } }]
+    t.canReply = true
+    t.contextValue = 'note'
+    const list = threads.get(uri.fsPath) || []
+    if (!list.includes(t)) list.push(t)
+    threads.set(uri.fsPath, list)
+    return t
+  }
+
+  /** Every comment, with the line it is on as it reads now — for the agent. */
+  function notes(doc) {
+    return (threads.get(doc.uri.fsPath) || []).flatMap((t) => t.comments.map((c) => {
+      const line = t.range.start.line
+      const text = doc.lineAt(Math.min(line, doc.lineCount - 1)).text.trim()
+      return `- Line ${line + 1}${text ? ` («${text.slice(0, 120)}»)` : ''}: ${typeof c.body === 'string' ? c.body : c.body.value}`
+    }))
+  }
+
+  function clear(file) {
+    for (const t of threads.get(file) || []) t.dispose()
+    threads.delete(file)
+  }
+
+  /** Opens a panel's pending plan as a document (written once, then edited in place). */
+  async function open(panel) {
+    const pending = panel?.pendingPlan
+    if (!pending) return null
+    if (!pending.file) {
+      pending.file = planFile(vscode.workspace.workspaceFolders?.[0]?.uri.fsPath, `${panel.id || 'plan'}-${pending.id}`)
+      fs.mkdirSync(path.dirname(pending.file), { recursive: true })
+      fs.writeFileSync(pending.file, `${pending.plan.trim()}\n`)
+    }
+    const doc = await vscode.workspace.openTextDocument(pending.file)
+    pending.doc = doc
+    await vscode.window.showTextDocument(doc, { preview: false, viewColumn: vscode.ViewColumn.Beside })
+    return doc
+  }
+
+  /** Answers the plan from its document: approved in a mode, or sent back with the comments. */
+  async function answer(uri, approved, mode) {
+    const file = uri?.fsPath || vscode.window.activeTextEditor?.document.uri.fsPath
+    const panel = file && owner(file)
+    if (!panel) { vscode.window.showInformationMessage('No plan is waiting for an answer in this file.'); return false }
+    const doc = vscode.workspace.textDocuments.find((d) => d.uri.fsPath === file)
+    if (doc?.isDirty) await doc.save()
+    if (approved && !mode) {
+      const pick = await vscode.window.showQuickPick(MODES.map((m) => ({ ...m, description: '' })), { title: 'Approve the plan' })
+      if (!pick) return false
+      mode = pick.id
+    }
+    const comments = doc ? notes(doc) : []
+    const feedback = approved ? '' : comments.length
+      ? `Comments on the plan:\n${comments.join('\n')}` : 'Revise the plan (see the edited version).'
+    const id = panel.pendingPlan.id
+    panel.post({ type: 'planClosed', id })
+    await panel.onMessage({ type: 'planAnswer', id, approved, mode, feedback })
+    clear(file)
+    return true
+  }
+
+  const add = (d) => context.subscriptions.push(d)
+  add(vscode.commands.registerCommand('aipictury.plan.open', () => open(registry.active())))
+  add(vscode.commands.registerCommand('aipictury.plan.approve', (uri, mode) => answer(uri, true, mode)))
+  add(vscode.commands.registerCommand('aipictury.plan.revise', (uri) => answer(uri, false)))
+  add(vscode.commands.registerCommand('aipictury.plan.addNote', (reply) => addNote(reply.thread.uri, reply.thread.range.start.line, reply.text, reply.thread)))
+  add(vscode.commands.registerCommand('aipictury.plan.deleteNote', (thread) => {
+    for (const [file, list] of threads) threads.set(file, list.filter((t) => t !== thread))
+    thread?.dispose()
+  }))
+  return { open, addNote, notes, answer, planFile }
+}
+
+module.exports = { register, planFile, MODES }

package/ext/plugins.js

@@ -0,0 +1,243 @@
+'use strict'
+// Plugins in Claude Code's format: a folder with .claude-plugin/plugin.json and, beside it,
+// commands/ (slash commands, as /plugin:command), agents/ (helper agents), skills/,
+// output-styles/, hooks/hooks.json and .mcp.json. Marketplaces in Claude Code's format too
+// (.claude-plugin/marketplace.json): from GitHub (owner/repo), a git URL or a folder. So the
+// plugins written for Claude Code install and work here.
+//
+//   ~/.aipictury/plugins/known_marketplaces.json   the marketplaces added
+//   ~/.aipictury/plugins/marketplaces/<name>/      their files
+//   ~/.aipictury/plugins/installed.json            what is installed, and where
+//   ~/.aipictury/plugins/cache/<market>/<plugin>/  each plugin's files
+// Whether one is on is the settings files' "enabledPlugins": { "name@market": true }, at a
+// level (you, the project, you in the project). Plugins installed by Claude Code itself and
+// enabled in its settings are read too, never changed.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { execFile } = require('child_process')
+const { home } = require('./sessions')
+const prefs = require('./prefs')
+
+const root = () => path.join(home(), 'plugins')
+const readJson = (file, fallback = null) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return fallback } }
+const writeJson = (file, data) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`)
+  fs.renameSync(tmp, file)
+}
+const knownFile = () => path.join(root(), 'known_marketplaces.json')
+const installedFile = () => path.join(root(), 'installed.json')
+const NAME = /^[\w.-]{1,64}$/
+
+// Asynchronous: a clone takes seconds to minutes, and a synchronous one would freeze every
+// extension of the window (they share one extension host) while it runs.
+function git(args, cwd, timeout = 120_000) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } },
+      (error, stdout, stderr) => {
+        if (error) reject(new Error(`git ${args[0]} failed: ${String(stderr || error.message).trim().split('\n').pop()}`, { cause: error }))
+        else resolve(stdout)
+      })
+  })
+}
+
+/** "owner/repo" → a GitHub URL; a URL as it is; anything else is a folder. */
+function sourceOf(text) {
+  const t = String(text || '').trim()
+  if (/^[\w.-]+\/[\w.-]+$/.test(t) && !fs.existsSync(t)) return { kind: 'git', url: `https://github.com/${t}.git`, label: t }
+  if (/^(https?:\/\/|git@|ssh:\/\/)/.test(t)) return { kind: 'git', url: t, label: t }
+  const dir = path.resolve(t.replace(/^~(?=\/|$)/, os.homedir()))
+  if (!fs.existsSync(dir)) throw new Error(`no such marketplace: ${t} (owner/repo, a git URL, or a folder)`)
+  return { kind: 'dir', dir, label: dir }
+}
+
+/** A clone (or a copy) of `source` in a fresh folder; optionally a ref (branch, tag) or commit. */
+async function fetchInto(source, dest, { ref, sha } = {}) {
+  fs.rmSync(dest, { recursive: true, force: true })
+  fs.mkdirSync(path.dirname(dest), { recursive: true })
+  if (source.kind === 'dir') { fs.cpSync(source.dir, dest, { recursive: true, filter: (p) => !/[\\/]\.git([\\/]|$)/.test(p) }); return }
+  if (sha) {
+    await git(['clone', '--filter=blob:none', '--no-checkout', source.url, dest])
+    await git(['checkout', '--quiet', sha], dest)
+  } else {
+    await git(['clone', '--depth', '1', ...(ref ? ['--branch', ref] : []), source.url, dest])
+  }
+  fs.rmSync(path.join(dest, '.git'), { recursive: true, force: true })
+}
+
+// ---- marketplaces ----
+
+function marketplaces() { return readJson(knownFile(), {}) }
+
+/** Adds a marketplace (GitHub owner/repo, a git URL or a folder). Returns its name and plugins. */
+async function addMarketplace(text) {
+  const source = sourceOf(text)
+  const tmp = path.join(root(), 'marketplaces', `.adding-${process.pid}-${Date.now()}`)
+  try {
+    await fetchInto(source, tmp)
+    const manifest = readJson(path.join(tmp, '.claude-plugin', 'marketplace.json'))
+    if (!manifest?.name || !Array.isArray(manifest.plugins)) throw new Error('that is not a marketplace: no .claude-plugin/marketplace.json with a name and plugins')
+    if (!NAME.test(manifest.name)) throw new Error(`a marketplace name that cannot be used: ${manifest.name}`)
+    const dest = path.join(root(), 'marketplaces', manifest.name)
+    fs.rmSync(dest, { recursive: true, force: true })
+    fs.renameSync(tmp, dest)
+    const known = marketplaces()
+    known[manifest.name] = { source: source.kind === 'dir' ? { dir: source.dir } : { url: source.url }, label: source.label, path: dest, updated: Date.now() }
+    writeJson(knownFile(), known)
+    return { name: manifest.name, plugins: manifest.plugins.length }
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }) }
+}
+
+async function updateMarketplace(name) {
+  const m = marketplaces()[name]
+  if (!m) throw new Error(`no marketplace ${name}`)
+  return addMarketplace(m.source.dir || m.source.url)
+}
+
+function removeMarketplace(name) {
+  const known = marketplaces()
+  if (!known[name]) throw new Error(`no marketplace ${name}`)
+  for (const id of Object.keys(installed())) if (id.endsWith(`@${name}`)) uninstall(id)
+  fs.rmSync(known[name].path, { recursive: true, force: true })
+  delete known[name]
+  writeJson(knownFile(), known)
+}
+
+/** Every plugin every marketplace offers: { id, name, market, description, version, installed }. */
+function available() {
+  const have = installed()
+  const out = []
+  for (const [market, m] of Object.entries(marketplaces())) {
+    const manifest = readJson(path.join(m.path, '.claude-plugin', 'marketplace.json'), { plugins: [] })
+    for (const p of manifest.plugins || []) {
+      const id = `${p.name}@${market}`
+      out.push({ id, name: p.name, market, description: p.description || '', version: p.version || '', category: p.category, installed: !!have[id], entry: p })
+    }
+  }
+  return out
+}
+
+// ---- installing ----
+
+function installed() { return readJson(installedFile(), {}) }
+
+/** Where a plugin's files come from, as a marketplace entry says. */
+function resolveSource(entry, marketDir) {
+  const src = entry.source
+  if (typeof src === 'string') {
+    const dir = path.resolve(marketDir, src)
+    if (!dir.startsWith(marketDir)) throw new Error(`${entry.name}: a source outside its marketplace`)
+    return { source: { kind: 'dir', dir } }
+  }
+  if (src?.source === 'github' && src.repo) return { source: { kind: 'git', url: `https://github.com/${src.repo}.git` }, ref: src.ref, sha: src.sha, sub: src.path }
+  if ((src?.source === 'url' || src?.source === 'git') && src.url) return { source: { kind: 'git', url: src.url }, ref: src.ref, sha: src.sha, sub: src.path }
+  if (src?.source === 'git-subdir' && src.url) return { source: { kind: 'git', url: src.url }, ref: src.ref, sha: src.sha, sub: src.path }
+  throw new Error(`${entry.name}: a kind of source not supported here (${src?.source || typeof src})`)
+}
+
+/** Installs name@market, and turns it on at a level ('user', 'project' or 'local'). */
+async function install(id, { folder, level = 'user' } = {}) {
+  const [name, market] = String(id).split('@')
+  const m = marketplaces()[market]
+  if (!m) throw new Error(`no marketplace ${market} — add it first`)
+  const entry = available().find((p) => p.id === id)?.entry
+  if (!entry) throw new Error(`${market} has no plugin ${name}`)
+  const how = resolveSource(entry, m.path)
+  const dest = path.join(root(), 'cache', market, name)
+  if (how.sub) {
+    const tmp = `${dest}.fetch-${process.pid}`
+    try {
+      await fetchInto(how.source, tmp, how)
+      const dir = path.resolve(tmp, how.sub)
+      if (!dir.startsWith(tmp) || !fs.existsSync(dir)) throw new Error(`${name}: ${how.sub} is not in its repository`)
+      fs.rmSync(dest, { recursive: true, force: true })
+      fs.cpSync(dir, dest, { recursive: true })
+    } finally { fs.rmSync(tmp, { recursive: true, force: true }) }
+  } else {
+    await fetchInto(how.source, dest, how)
+  }
+  const manifest = readJson(path.join(dest, '.claude-plugin', 'plugin.json'), {})
+  const list = installed()
+  list[id] = { path: dest, version: manifest.version || entry.version || '', description: manifest.description || entry.description || '', installedAt: Date.now() }
+  writeJson(installedFile(), list)
+  setEnabled(id, true, { folder, level })
+  return { id, path: dest, version: list[id].version }
+}
+
+function uninstall(id, { folder } = {}) {
+  const list = installed()
+  if (!list[id]) throw new Error(`${id} is not installed`)
+  fs.rmSync(list[id].path, { recursive: true, force: true })
+  delete list[id]
+  writeJson(installedFile(), list)
+  for (const level of ['user', 'project', 'local']) {
+    try { prefs.edit(folder, level, (data) => { if (data.enabledPlugins) { delete data.enabledPlugins[id]; if (!Object.keys(data.enabledPlugins).length) delete data.enabledPlugins } }) } catch { /* no such level here */ }
+  }
+}
+
+function setEnabled(id, on, { folder, level = 'user' } = {}) {
+  return prefs.edit(folder, level, (data) => { data.enabledPlugins = { ...(data.enabledPlugins || {}), [id]: !!on } })
+}
+
+/** Plugins Claude Code installed itself (read-only): id → install path. */
+function claudeInstalled() {
+  const dir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')
+  const data = readJson(path.join(dir, 'plugins', 'installed_plugins.json'), {})
+  const out = {}
+  for (const [id, v] of Object.entries(data.plugins || data || {})) {
+    const entry = Array.isArray(v) ? v[0] : v
+    if (entry?.installPath && fs.existsSync(entry.installPath)) out[id] = entry.installPath
+  }
+  return out
+}
+
+/** The plugins that are on here: [{ id, name, root, fromClaudeCode }]. */
+function enabled(folder) {
+  const on = prefs.load(folder).merged.enabledPlugins || {}
+  const ours = installed()
+  const theirs = claudeInstalled()
+  const out = []
+  for (const [id, yes] of Object.entries(on)) {
+    if (yes !== true) continue
+    const dir = ours[id]?.path || theirs[id]
+    if (dir && fs.existsSync(dir)) out.push({ id, name: id.split('@')[0], root: dir, fromClaudeCode: !ours[id] })
+  }
+  return out
+}
+
+// ---- what plugins bring ----
+
+const withRoot = (value, dir) => JSON.parse(JSON.stringify(value).replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, dir.replace(/\\/g, '\\\\')))
+
+/** The folders of one kind (commands, agents, skills, output-styles) of the plugins that are on. */
+function dirs(folder, kind) {
+  return enabled(folder).map((p) => ({ dir: path.join(p.root, kind), plugin: p.name })).filter((d) => fs.existsSync(d.dir))
+}
+
+/** Their hooks, as the settings files give them (event → groups), ${CLAUDE_PLUGIN_ROOT} filled in. */
+function hooks(folder) {
+  const out = {}
+  for (const p of enabled(folder)) {
+    const data = readJson(path.join(p.root, 'hooks', 'hooks.json'))
+    for (const [event, groups] of Object.entries(data?.hooks || {})) {
+      for (const g of groups || []) (out[event] ||= []).push({ ...withRoot(g, p.root), level: 'plugin', file: path.join(p.root, 'hooks', 'hooks.json'), editable: false, plugin: p.name })
+    }
+  }
+  return out
+}
+
+/** Their MCP servers: name → config, ${CLAUDE_PLUGIN_ROOT} filled in. */
+function mcpServers(folder) {
+  const out = {}
+  for (const p of enabled(folder)) {
+    const manifest = readJson(path.join(p.root, '.claude-plugin', 'plugin.json'), {})
+    const servers = readJson(path.join(p.root, '.mcp.json'))?.mcpServers || (typeof manifest.mcpServers === 'object' ? manifest.mcpServers : {})
+    for (const [name, config] of Object.entries(servers)) out[name] = { ...withRoot(config, p.root), plugin: p.name }
+  }
+  return out
+}
+
+module.exports = { marketplaces, addMarketplace, updateMarketplace, removeMarketplace, available, installed, install, uninstall,
+  setEnabled, enabled, dirs, hooks, mcpServers, sourceOf, root }