claude-novice 0.2.0

package/hooks/hooks.json

@@ -0,0 +1,107 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-submit.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptExpansion": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-expansion.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool-use.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use-failure.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolBatch": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-batch.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-end.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-novice",
+  "version": "0.2.0",
+  "description": "바이브 코딩 입문자용 Claude Code 플러그인 — 용어 스캐폴딩·안전 게이트·서비스 CLI 부트스트랩 | A Claude Code plugin for vibe-coding beginners — term scaffolding, safety gate, service CLI bootstrap",
+  "type": "module",
+  "license": "MIT",
+  "author": "SHC (hjsh200219)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hjsh200219/novice.git"
+  },
+  "homepage": "https://github.com/hjsh200219/novice#readme",
+  "bugs": {
+    "url": "https://github.com/hjsh200219/novice/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "beginner",
+    "onboarding",
+    "korean",
+    "safety",
+    "vibe-coding"
+  ],
+  "files": [
+    ".claude-plugin/",
+    "config/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "ARCHITECTURE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "verify-docs": "node scripts/verify-docs.mjs",
+    "pretest": "node scripts/verify-docs.mjs",
+    "test": "node --test tests/unit/*.test.js tests/integration/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage tests/unit/*.test.js tests/integration/*.test.js",
+    "prepublishOnly": "npm test"
+  }
+}

package/scripts/bootstrap-engine.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// Common bootstrap engine: resolve → preflight → plan → approve → apply → verify → recover.
+// One engine for every provider — the differences live in versioned manifest data.
+// Automation boundary: detect → install → login → auth verify. Nothing beyond.
+//
+// Invariants:
+// - exec-form argv only; no shell strings, no curl|bash.
+// - preflight is strictly read-only (detect/version_check/auth_status argv only).
+// - install and login each require their own explicit approval before apply.
+// - plaintext credential fallback aborts auto-login when the manifest says so.
+// - audit state stores service id, manifest revision, step names, exit statuses — never
+//   argv text, stdout/stderr, or credential values.
+import path from 'node:path';
+import { validateManifest, loadTier1Manifest, buildAdHocManifest } from './lib/manifest.js';
+import { dataDir, writeJsonAtomic, readJsonSafe, assertSafeId } from './lib/state.js';
+import { planCapability } from './lib/capability-router.js';
+
+function auditPath(sessionId, serviceId, env) {
+  return path.join(
+    dataDir(env),
+    'sessions',
+    assertSafeId(sessionId, 'session id'),
+    'bootstrap',
+    `${assertSafeId(serviceId, 'service id')}.json`,
+  );
+}
+
+function matchSuccess(spec, result) {
+  if (!spec) return result.code === 0;
+  if (spec.exit_code !== undefined && result.code !== spec.exit_code) return false;
+  if (spec.exit_code_not !== undefined && result.code === spec.exit_code_not) return false;
+  if (spec.stdout_regex && !new RegExp(spec.stdout_regex).test(result.stdout ?? '')) return false;
+  return true;
+}
+
+export function createEngine({
+  exec,
+  platform = process.platform,
+  interactive = true,
+  env = process.env,
+  now = () => new Date().toISOString(),
+} = {}) {
+  if (typeof exec !== 'function') throw new Error('createEngine requires an injected exec(argv)');
+
+  async function run(argv) {
+    if (!Array.isArray(argv) || argv.some((t) => typeof t !== 'string')) {
+      throw new Error('engine only executes exec-form argv arrays');
+    }
+    return exec(argv);
+  }
+
+  function audit(sessionId, manifest, step, exitStatus) {
+    if (!sessionId) return;
+    try {
+      const file = auditPath(sessionId, manifest.service_id, env);
+      const current = readJsonSafe(file, {
+        service_id: manifest.service_id,
+        manifest_revision: manifest.manifest_revision ?? null,
+        tier: manifest.tier ?? null,
+        steps: [],
+      });
+      current.steps.push({ step, exit_status: exitStatus, at: now() });
+      writeJsonAtomic(file, current);
+    } catch {
+      // audit is best-effort; it must never carry more than step/exit metadata anyway
+    }
+  }
+
+  return {
+    resolve(serviceId, adHocInput = null) {
+      const tier1 = loadTier1Manifest(serviceId, env);
+      if (tier1) return { tier: 1, manifest: tier1 };
+      if (adHocInput) {
+        const built = buildAdHocManifest(adHocInput);
+        if (built.ok) return { tier: 2, manifest: built.manifest, requiresUserApproval: true };
+        return { mode: 'guided_manual', reason: built.reason };
+      }
+      return {
+        mode: 'guided_manual',
+        reason: `'${serviceId}'는 검토된 manifest에 없어요. 공식 문서 URL과 package coordinate를 조사해 사용자 승인을 받거나 guided manual로 진행하세요.`,
+      };
+    },
+
+    async preflight(manifest, { plaintextDetected = false } = {}) {
+      const detect = await run(manifest.detect.argv);
+      const installed = matchSuccess(manifest.detect.success, detect);
+      let versionOk = false;
+      let authenticated = false;
+      if (installed) {
+        const version = await run(manifest.version_check.argv);
+        versionOk = matchSuccess(manifest.version_check.success, version);
+        const auth = await run(manifest.auth_status.argv);
+        authenticated = matchSuccess(manifest.auth_status.success, auth);
+      }
+      const cs = manifest.credential_store;
+      const plaintextRisk = plaintextDetected || cs.secure_storage === false;
+      return {
+        installed,
+        version_ok: versionOk,
+        authenticated,
+        interactive,
+        credential_store: cs,
+        plaintext_risk: plaintextRisk,
+        abort_login: plaintextRisk && cs.abort_auto_login_on_plaintext === true,
+      };
+    },
+
+    plan(manifest, preflight) {
+      const steps = [];
+      if (!preflight.installed || !preflight.version_ok) {
+        const installer = manifest.installers.find((i) => i.os.includes(platform)) ?? manifest.installers[0];
+        steps.push({
+          kind: 'install',
+          approval_required: true,
+          argv: installer.argv,
+          disclosure:
+            `설치: ${manifest.binary} — package coordinate '${installer.package_coordinate}' (${installer.package_manager})\n` +
+            `공식 근거: ${manifest.docs_url}\n` +
+            `전역 변경: ${(installer.global_changes ?? []).join(', ') || '없음'}\n` +
+            `되돌리기: ${JSON.stringify(manifest.uninstall[installer.package_manager] ?? Object.values(manifest.uninstall)[0])}`,
+        });
+      }
+      if (!preflight.authenticated) {
+        if (!preflight.interactive) {
+          steps.push({
+            kind: manifest.noninteractive_policy.login === 'deny' ? 'denied_login' : 'guided_manual',
+            policy: manifest.noninteractive_policy.login,
+            guidance: `비대화형 환경이라 자동 로그인하지 않아요. ${manifest.noninteractive_policy.reason}`,
+          });
+        } else if (preflight.abort_login) {
+          steps.push({
+            kind: 'aborted_login',
+            reason: 'plaintext credential fallback',
+            guidance:
+              `이 환경에서는 인증 정보가 평문으로 저장될 수 있어 자동 로그인을 중단했어요.\n` +
+              `저장 위치: ${manifest.credential_store.plaintext_fallback_location ?? manifest.credential_store.storage}\n` +
+              `직접 로그인한 경우 제거: ${JSON.stringify(manifest.logout.argv)}\n${manifest.credential_store.abort_note ?? ''}`,
+          });
+        } else {
+          steps.push({
+            kind: 'login',
+            approval_required: true,
+            argv: manifest.login.argv,
+            disclosure:
+              `로그인: ${JSON.stringify(manifest.login.argv)}\n` +
+              `인증 저장: ${manifest.credential_store.storage}\n` +
+              `사용자가 직접 완료: ${(manifest.login.user_completes ?? []).join(', ')}\n` +
+              `되돌리기(logout): ${JSON.stringify(manifest.logout.argv)}`,
+          });
+        }
+      }
+      return { service_id: manifest.service_id, steps };
+    },
+
+    async apply(manifest, plan, approvals = {}, sessionId = null) {
+      const results = [];
+      for (const step of plan.steps) {
+        if (step.kind === 'guided_manual' || step.kind === 'aborted_login' || step.kind === 'denied_login') {
+          results.push({ step: step.kind, ok: false, skipped: true, guidance: step.guidance });
+          continue;
+        }
+        if (step.approval_required && approvals[step.kind] !== true) {
+          results.push({ step: step.kind, ok: false, skipped: true, reason: 'approval_missing' });
+          continue;
+        }
+        const result = await run(step.argv);
+        audit(sessionId, manifest, step.kind, result.code);
+        const ok = result.code === 0;
+        results.push({ step: step.kind, ok, exit_status: result.code });
+        if (!ok) break; // stop on first failure; recover() reports the rest
+      }
+      return results;
+    },
+
+    async verify(manifest) {
+      const version = await run(manifest.version_check.argv);
+      const auth = await run(manifest.auth_status.argv);
+      return {
+        installed_ok: matchSuccess(manifest.version_check.success, version),
+        auth_ok: matchSuccess(manifest.auth_status.success, auth),
+      };
+    },
+
+    recover(manifest, sessionId = null) {
+      const auditState = sessionId
+        ? readJsonSafe(auditPath(sessionId, manifest.service_id, env), { steps: [] })
+        : { steps: [] };
+      return {
+        completed_steps: auditState.steps,
+        remaining_side_effects: manifest.side_effects,
+        retry_guidance: '완료된 단계는 재실행 시 preflight가 건너뛰어요. 실패한 단계만 다시 승인해 진행하세요.',
+        logout_argv: manifest.logout.argv,
+        uninstall_options: manifest.uninstall,
+        auto_cleanup: false,
+      };
+    },
+  };
+}
+
+// Full state-machine convenience wrapper.
+export async function runBootstrap(engine, serviceId, { approvals = {}, adHocInput = null, sessionId = null, plaintextDetected = false } = {}) {
+  const resolved = engine.resolve(serviceId, adHocInput);
+  if (resolved.mode === 'guided_manual') return { phase: 'resolve', ...resolved };
+
+  const manifest = resolved.manifest;
+  const { valid, errors } = validateManifest(manifest);
+  if (!valid) return { phase: 'resolve', mode: 'guided_manual', reason: `manifest invalid: ${errors.join('; ')}` };
+
+  const preflight = await engine.preflight(manifest, { plaintextDetected });
+  const plan = engine.plan(manifest, preflight);
+  if (plan.steps.length === 0) {
+    const verified = await engine.verify(manifest);
+    return { phase: 'verify', tier: resolved.tier, already_complete: true, preflight, verified };
+  }
+  const applied = await engine.apply(manifest, plan, approvals, sessionId);
+  const failed = applied.some((r) => r.ok === false && r.skipped !== true);
+  const verified = failed ? null : await engine.verify(manifest);
+  return {
+    phase: failed ? 'recover' : 'verify',
+    tier: resolved.tier,
+    preflight,
+    plan,
+    applied,
+    verified,
+    recover: failed ? engine.recover(manifest, sessionId) : null,
+  };
+}
+
+// Capability-routed entry point: pick the path (CLI → allowlisted MCP → visible Chrome →
+// guided manual) per PRD §4.3, then only the `cli` path drives the manifest engine here.
+// mcp/chrome/guided_manual return a plan for the model/user to carry out — the plugin never
+// invokes MCP tools or drives Chrome itself.
+export async function setupService(engine, serviceId, capability = 'bootstrap', ctx = {}, opts = {}) {
+  const plan = planCapability(serviceId, capability, ctx);
+  if (plan.path !== 'cli') {
+    return { routed: plan.path, plan };
+  }
+  const bootstrap = await runBootstrap(engine, serviceId, opts);
+  return { routed: 'cli', plan, bootstrap };
+}

package/scripts/lib/capability-router.js

@@ -0,0 +1,170 @@
+// Capability router for external-service setup.
+//
+// PRD §4.3: capability priority is CLI → allowlisted 공식 MCP → visible Chrome → guided manual.
+// This module is the deterministic decision/validation layer — it picks the path, validates an
+// MCP server candidate against the allowlist, judges Chrome availability, and downgrades safely.
+//
+// What it does NOT do (by design / platform reality): it does not spawn MCP servers, invoke MCP
+// tools, or drive Chrome. Those side effects stay model-driven (the model calls an allowlisted
+// MCP tool; the PreToolUse gate still guards it) and user-driven (login/CAPTCHA/MFA/final submit
+// happen in visible Chrome by the user). The router produces the plan and the refusals.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pluginRoot } from './secrets.js';
+
+let cached = null;
+export function loadCapabilities(env = process.env) {
+  if (cached) return cached;
+  const file = path.join(pluginRoot(env), 'config', 'service-capabilities.json');
+  cached = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return cached;
+}
+
+// ---- MCP candidate validation (two acceptance paths) ----
+//
+// candidate: what the runtime reports about an available MCP server plus the tools the model
+//   wants to use:
+//   { service_id?, server, transport, publisher, tools:[baseName],
+//     provenance:{verified},   // for the static-allowlist path
+//     registered:boolean,      // server is registered/connected in the user's Claude runtime
+//     userConsent:boolean }    // user explicitly approved using this server for this task
+//
+// Path 1 — static allowlist (pre-reviewed in service-capabilities.json): auto-usable, no
+//   per-use consent required. Strongest: server/transport/publisher/tools all pinned.
+// Path 2 — runtime-registered + explicit user consent: the user already added the server to
+//   their Claude config (that registration IS the provenance) AND explicitly consented to use
+//   it now. Limited to the tools the user consented to. Destructive tool calls are still
+//   blocked by the PreToolUse safety gate, and nothing is auto-installed.
+export function validateMcpCandidate(candidate, allowlist = [], capability = null) {
+  if (!candidate || typeof candidate !== 'object') return { allowed: false, reason: 'no-candidate' };
+
+  // Path 1: static allowlist.
+  const entry = Array.isArray(allowlist)
+    ? allowlist.find((e) => e.server === candidate.server && (!candidate.service_id || e.service_id === candidate.service_id))
+    : null;
+  if (entry) {
+    if (entry.transport !== candidate.transport) return { allowed: false, reason: 'transport-mismatch' };
+    if (entry.publisher !== candidate.publisher) return { allowed: false, reason: 'publisher-mismatch' };
+    if (candidate.provenance?.verified !== true) return { allowed: false, reason: 'provenance-unverified' };
+    if (capability && Array.isArray(entry.capabilities) && !entry.capabilities.includes(capability)) {
+      return { allowed: false, reason: 'capability-not-served' };
+    }
+    const wanted = Array.isArray(candidate.tools) ? candidate.tools : [];
+    const allowedSet = new Set(entry.tools || []);
+    const rejectedTool = wanted.find((t) => !allowedSet.has(t));
+    if (rejectedTool) return { allowed: false, reason: `tool-not-allowlisted:${rejectedTool}` };
+    return { allowed: true, basis: 'allowlist', entry, tools: wanted };
+  }
+
+  // Path 2: runtime-registered + explicit user consent.
+  const registered = candidate.registered === true;
+  const consented = candidate.userConsent === true;
+  if (registered && consented) {
+    return { allowed: true, basis: 'user-consent', tools: Array.isArray(candidate.tools) ? candidate.tools : [] };
+  }
+  if (registered && !consented) return { allowed: false, reason: 'registered-no-consent' };
+  if (consented && !registered) return { allowed: false, reason: 'consented-not-registered' };
+
+  return { allowed: false, reason: 'not-in-allowlist-and-no-consent' };
+}
+
+// ---- Chrome availability ----
+//
+// chromeEnv: { available: boolean (official Claude in Chrome connected), thirdPartyProvider: boolean }
+export function chromeDecision(chromeEnv, policy = {}) {
+  if (!chromeEnv || chromeEnv.available !== true) return { usable: false, reason: 'chrome-not-connected' };
+  if (chromeEnv.thirdPartyProvider === true) return { usable: false, reason: 'third-party-provider' };
+  return {
+    usable: true,
+    mode: policy.mode ?? 'visible-only',
+    user_completes: policy.user_completes ?? ['login', 'captcha', 'mfa', 'final-submit'],
+    reason: 'ok',
+  };
+}
+
+// ---- path resolution ----
+//
+// ctx: {
+//   cliAvailable: boolean,        // manifest preflight ok AND user did not refuse install
+//   cliRefusedOrFailed: boolean,  // user refused CLI install, or preflight failed
+//   mcpCandidate: object|null,
+//   chromeEnv: object|null,
+// }
+export function resolveCapability(serviceId, capability, ctx = {}, caps = loadCapabilities()) {
+  const priority = Array.isArray(caps.capability_priority)
+    ? caps.capability_priority
+    : ['cli', 'mcp', 'chrome', 'guided_manual'];
+
+  // A per-service capability may be pinned (e.g. provisioning/deploy → guided_manual).
+  const pinned = caps.services?.[serviceId]?.capabilities?.[capability];
+  const startIndex = pinned && priority.includes(pinned) ? priority.indexOf(pinned) : 0;
+
+  const ordered = [];
+  let chosen = null;
+
+  for (let i = startIndex; i < priority.length; i++) {
+    const p = priority[i];
+    let usable = false;
+    let reason = '';
+    let detail = null;
+
+    if (p === 'cli') {
+      // CLI is usable when it is available (Tier 1 preflight ok) OR the user explicitly
+      // consented to it (Tier 2 ad-hoc manifest confirmed_by_user), and was not refused/failed.
+      usable = (ctx.cliAvailable === true || ctx.cliUserConsent === true) && ctx.cliRefusedOrFailed !== true;
+      reason = usable ? 'ok' : ctx.cliRefusedOrFailed ? 'cli-refused-or-failed' : 'cli-unavailable';
+    } else if (p === 'mcp') {
+      const v = validateMcpCandidate(ctx.mcpCandidate, caps.mcp_allowlist, capability);
+      usable = v.allowed;
+      reason = v.allowed ? `ok:${v.basis}` : v.reason;
+      detail = v.allowed ? { basis: v.basis, entry: v.entry ?? null, tools: v.tools } : null;
+    } else if (p === 'chrome') {
+      const d = chromeDecision(ctx.chromeEnv, caps.chrome_policy);
+      usable = d.usable;
+      reason = d.reason;
+      detail = d.usable ? d : null;
+    } else if (p === 'guided_manual') {
+      usable = true;
+      reason = 'terminal-fallback';
+    }
+
+    ordered.push({ path: p, usable, reason });
+    if (usable && !chosen) chosen = { path: p, detail };
+  }
+
+  // guided_manual is always in the walk, so chosen is never null.
+  return { service_id: serviceId, capability, path: chosen.path, detail: chosen.detail, ordered };
+}
+
+// Human/model-readable plan (Korean) describing what runs and who does what.
+export function planCapability(serviceId, capability, ctx = {}, caps = loadCapabilities()) {
+  const r = resolveCapability(serviceId, capability, ctx, caps);
+  const skipped = r.ordered.filter((o) => !o.usable && o.path !== r.path).map((o) => `${o.path}(${o.reason})`);
+  let guidance;
+  switch (r.path) {
+    case 'cli':
+      guidance = 'CLI 부트스트랩(setup-service manifest 엔진)으로 진행합니다. 설치·로그인 각각 승인이 필요합니다.';
+      break;
+    case 'mcp': {
+      const server = r.detail.entry?.server ?? ctx.mcpCandidate?.server ?? '등록된 서버';
+      const source =
+        r.detail.basis === 'allowlist'
+          ? `allowlist에 검증된 공식 MCP(${server})`
+          : `사용자가 명시적으로 동의한 등록된 MCP(${server})`;
+      guidance =
+        `${source}로 진행합니다. ` +
+        `사용 가능한 tool: ${r.detail.tools.join(', ') || '(동의한 tool 범위)'}. ` +
+        'MCP tool 호출은 모델이 수행하며 PreToolUse 안전 게이트가 계속 검사합니다.';
+      break;
+    }
+    case 'chrome':
+      guidance =
+        'visible Chrome(공식 Claude in Chrome)으로 진행합니다. ' +
+        `login/CAPTCHA/MFA와 최종 submit(${r.detail.user_completes.join(', ')})은 사용자가 직접 완료합니다.`;
+      break;
+    default:
+      guidance =
+        'guided manual로 안내합니다. 무엇을·왜·어느 명령/화면에서 하는지 단계별로 설명하고 사용자가 직접 실행합니다.';
+  }
+  return { ...r, skipped, guidance };
+}