@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/cli-doc-commands.js

@@ -0,0 +1,352 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+function cmdValidate(rest, io) {
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { parseFlags } = require('./cli-flags');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { validateBlueprint } = require('./validate');
+    const f = parseFlags(rest);
+    // 게이트 실패(1)와 구분: 필수 플래그 누락은 호출 형식 오류(2). 없으면
+    // validate가 빈 blueprint로 구조 실패를 내어 사용법 문제를 위장한다.
+    if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+        io.err('validate: --blueprint is required\n');
+        return 2;
+    }
+    const repoRoot = (f.repo || process.cwd());
+    // 빈 문자열을 넘기면 validate가 알 수 없는 gate로 본다. 생략일 때만
+    // 라이브러리 기본(게이트 없이 구조 검사)이 살아 있다.
+    const gate = typeof f.gate === 'string' ? f.gate : undefined;
+    const result = validateBlueprint({
+        repoRoot,
+        blueprintDir: f.blueprint,
+        gate,
+    });
+    io.out(`${JSON.stringify(result, null, 2)}\n`);
+    // ok=false는 실패 코드가 있는 검사 결과 — 사용법이 아니므로 1.
+    return result.ok ? 0 : 1;
+}
+/**
+ * `--blueprint` 대상의 verify 명령을 실행하고 증적을 기록한다.
+ * 통과하면 lease·pointer commit task를 `ready`에서 `verified`로 올린다.
+ *
+ * @param {string[]} rest - CLI 나머지 인자(`--blueprint`, `--repo`)
+ * @param {CliIo} io - stdout/stderr 기록기
+ * @returns {number} 성공 0, 실행 실패 1, 플래그 누락 2
+ */
+function cmdVerify(rest, io) {
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { catchMessage } = require('./guards');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { parseFlags } = require('./cli-flags');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { runSelectedVerification } = require('./verification-target');
+    const f = parseFlags(rest);
+    // validate와 같은 2: 대상 없이 돌리면 게이트 실패로 위장된다.
+    if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+        io.err('verify: --blueprint is required\n');
+        return 2;
+    }
+    try {
+        const result = runSelectedVerification({
+            repoRoot: (f.repo || process.cwd()),
+            blueprintDir: f.blueprint,
+            markTaskVerified: true,
+        });
+        io.out(`${JSON.stringify(result, null, 2)}\n`);
+        return result.ok ? 0 : 1;
+    }
+    catch (error) {
+        // VERIFY_DOCUMENT_MISSING 등은 throw. 플래그는 이미 통과했으므로
+        // 사용법(2)이 아니라 실행 실패(1).
+        io.err(`verify: ${catchMessage(error)}\n`);
+        return 1;
+    }
+}
+function cmdScaffold(rest, io) {
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { catchMessage } = require('./guards');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { parseFlags } = require('./cli-flags');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { AREA_SLUG_RE, scaffoldEpic, scaffoldBlueprint, scaffoldExplain, scaffoldTask, scaffoldContextReview } = require('./scaffold');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { isNumericContextId } = require('./paths');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { isCanonicalEpicDir, isValidBlueprintOrder } = require('./layout');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { parseContextPath, validateSlug } = require('./context-ids');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { readEpicRegistry } = require('./epic-registry');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { SCALE_ENUM, DEFAULT_SCALE } = require('./schema');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { readVerifyPolicy } = require('./config');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { nowIsoKst } = require('./time');
+    // kind는 위치 인자 — parseFlags에 rest 전체를 주면 epic이 플래그 키로 사라진다.
+    const [kind, ...flagArgs] = rest;
+    const f = parseFlags(flagArgs);
+    const repoRoot = (f.repo || process.cwd());
+    // 테스트가 시각을 고정하려고 --timestamp를 넘긴다. 없으면 KST now.
+    const timestamp = typeof f.timestamp === 'string' ? f.timestamp : nowIsoKst();
+    let created;
+    try {
+        if (kind === 'epic' || kind === 'blueprint') {
+            // 새 문서의 형식을 정한다. blueprint는 부모 epic 경로가, 경로가 아직 없는 새 epic은 등록부 버전(v2)이
+            // 정한다 — 플래그·환경 변수로 형식을 켜지 않아야 같은 저장소에서 epic마다 형식이 흔들리지 않는다.
+            // 등록부 부재·invalid는 번호 형식(기존 동작)으로 둔다. invalid의 보고는 S35 소관이다.
+            const epicDirFlag = f['epic-dir'];
+            const parentFormat = kind === 'blueprint' && typeof epicDirFlag === 'string' && isCanonicalEpicDir(epicDirFlag)
+                ? parseContextPath(epicDirFlag)?.format
+                : undefined;
+            const registryRead = kind === 'epic' ? readEpicRegistry(repoRoot) : null;
+            const slugForm = parentFormat === 'slug'
+                || (registryRead !== null && registryRead.status === 'ok' && registryRead.registry.version === 2);
+            if (slugForm) {
+                // slug 형식은 번호를 받지 않는다. 조용히 무시하면 번호 디렉터리를 만든 줄 오해하므로 거절한다.
+                if (f.id !== undefined) {
+                    io.err(kind === 'epic'
+                        ? 'scaffold epic: the v2 registry names epics by slug; drop --id and pass --name <slug>\n'
+                        : 'scaffold blueprint: a slug epic orders blueprints with --order <n>; drop --id\n');
+                    return 2;
+                }
+            }
+            else if (parentFormat === 'numeric' && f.order !== undefined) {
+                io.err('scaffold blueprint: a numbered epic takes --id <ddd>, not --order\n');
+                return 2;
+            }
+            else if (!isNumericContextId(f.id)) {
+                // EPIC-001 / 1 / 01 거절 — 정본은 zero-pad 세 자리만. 라이브러리 throw와 메시지를 맞춤.
+                io.err(`scaffold: --id must be a zero-padded three-digit id (\\d{3}), got ${JSON.stringify(f.id)}\n`);
+                return 2;
+            }
+            // id 형식 다음에 name. 잘못된 id를 --name 누락으로 안내하면 고칠 곳이 빗나간다.
+            if (typeof f.name !== 'string' || f.name === '') {
+                io.err(`scaffold ${kind}: --name is required\n`);
+                return 2;
+            }
+            // 위 가드 뒤의 좁힌 값을 지역에 고정한다. 이후 `if (kind === 'epic')`로
+            // 갈라지면 TS가 epic|blueprint 가드 좁히기를 유지하지 않는다.
+            const name = f.name;
+            const description = typeof f.description === 'string' ? f.description : undefined;
+            if (kind === 'epic') {
+                created = scaffoldEpic({
+                    repoRoot, epicId: slugForm ? undefined : f.id, name, timestamp, description,
+                });
+            }
+            else {
+                // id/name 통과 뒤에만 epic-dir을 묻는다. 형식 오류를 부모 경로 누락과
+                // 같은 메시지로 섞지 않기 위함.
+                if (typeof f['epic-dir'] !== 'string' || f['epic-dir'] === '') {
+                    io.err('scaffold blueprint: --epic-dir is required\n');
+                    return 2;
+                }
+                // slug blueprint의 순서. `--order` 뒤에 값이 없으면 parseFlags가 true를 주므로 문자열 검사가
+                // 그 형태도 거른다. 되돌려 문자열화한 값이 입력과 같아야 해 `1.5`·`03`·`1e2` 같은 모호한 표기를 막는다.
+                let order;
+                if (parentFormat === 'slug') {
+                    const parsed = typeof f.order === 'string' ? Number(f.order) : Number.NaN;
+                    if (!isValidBlueprintOrder(parsed) || String(parsed) !== f.order) {
+                        io.err(`scaffold blueprint: --order must be a positive integer, got ${JSON.stringify(f.order)}\n`);
+                        return 2;
+                    }
+                    const slugViolation = validateSlug(name);
+                    if (slugViolation !== null) {
+                        io.err(`scaffold blueprint: --name must be a valid slug: ${slugViolation}\n`);
+                        return 2;
+                    }
+                    order = parsed;
+                }
+                // scale은 선택 인자다. 생략은 기존 계약(full)이고, 알 수 없는 값은
+                // 라이브러리에 닿기 전에 사용법 오류(2)로 거절해 파일을 하나도 만들지
+                // 않는다. `--scale` 뒤에 값이 없으면 parseFlags가 boolean true를 주므로
+                // 문자열 검사가 그 형태도 같이 거른다.
+                const scale = f.scale === undefined ? DEFAULT_SCALE : f.scale;
+                if (typeof scale !== 'string' || !SCALE_ENUM.includes(scale)) {
+                    io.err(`scaffold blueprint: --scale must be one of ${SCALE_ENUM.join('|')}, `
+                        + `got ${JSON.stringify(f.scale)}\n`);
+                    return 2;
+                }
+                // area·attribution도 선택 인자다. 값 없이 온 플래그(true)와 잘못된 모양은
+                // 파일을 쓰기 전에 사용법 오류(2)로 거절한다.
+                const area = f.area;
+                if (area !== undefined && (typeof area !== 'string' || !AREA_SLUG_RE.test(area))) {
+                    io.err(`scaffold blueprint: --area must be a lowercase slug, got ${JSON.stringify(area)}\n`);
+                    return 2;
+                }
+                const attribution = f.attribution;
+                if (attribution !== undefined && (typeof attribution !== 'string'
+                    || attribution.trim() === '' || /[\r\n]/.test(attribution))) {
+                    io.err('scaffold blueprint: --attribution must be a non-empty single line\n');
+                    return 2;
+                }
+                created = scaffoldBlueprint({
+                    repoRoot,
+                    epicDir: f['epic-dir'],
+                    ...(order === undefined ? { blueprintId: f.id } : { order }),
+                    name,
+                    timestamp,
+                    scale,
+                    area,
+                    attribution,
+                });
+            }
+        }
+        else if (kind === 'task') {
+            // --blueprint / --id 누락은 형식 오류보다 먼저 안내한다.
+            if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+                io.err('scaffold task: --blueprint is required\n');
+                return 2;
+            }
+            if (typeof f.id !== 'string' || f.id === '') {
+                io.err('scaffold task: --id is required\n');
+                return 2;
+            }
+            if (!isNumericContextId(f.id)) {
+                io.err(`scaffold: --id must be a zero-padded three-digit id (\\d{3}), got ${JSON.stringify(f.id)}\n`);
+                return 2;
+            }
+            const executionKind = f['execution-kind'] === undefined ? 'commit' : f['execution-kind'];
+            let dependsOn;
+            let verifyAllowlist;
+            if (executionKind === 'verification') {
+                if (typeof f['depends-on'] !== 'string' || f['depends-on'].trim() === '') {
+                    io.err('scaffold task: --depends-on is required for verification\n');
+                    return 2;
+                }
+                // parseFlags는 한 플래그에 한 문자열만 보존한다. fan-in은 쉼표 구분으로
+                // 받아 argv 하나를 유지하고, 빈 원소는 library shape 검사가 거절한다.
+                dependsOn = f['depends-on'].split(',').map((entry) => entry.trim());
+                if (typeof f.verify !== 'string' || f.verify.trim() === '') {
+                    io.err('scaffold task: --verify is required for verification\n');
+                    return 2;
+                }
+                const policy = readVerifyPolicy(repoRoot);
+                if (policy.ok === false) {
+                    io.err('scaffold task: verification config is invalid\n');
+                    return 2;
+                }
+                verifyAllowlist = policy.allowlist;
+            }
+            created = scaffoldTask({
+                repoRoot, blueprintDir: f.blueprint, taskId: f.id, timestamp,
+                executionKind, dependsOn, verify: f.verify, verifyAllowlist,
+            });
+        }
+        else if (kind === 'explain') {
+            // explain은 id/name이 없다. blueprint만 없으면 라이브러리가 경로 throw를 낸다.
+            if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+                io.err('scaffold explain: --blueprint is required\n');
+                return 2;
+            }
+            created = scaffoldExplain({ repoRoot, blueprintDir: f.blueprint, timestamp });
+        }
+        else if (kind === 'context-review') {
+            // explain과 같은 필수 플래그. 메시지를 kind별로 두어 호출자가 어느
+            // scaffold인지 알게 한다.
+            if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+                io.err('scaffold context-review: --blueprint is required\n');
+                return 2;
+            }
+            created = scaffoldContextReview({ repoRoot, blueprintDir: f.blueprint, timestamp });
+        }
+        else {
+            // 알려진 kind가 아니면 라이브러리를 호출하지 않는다. throw 메시지가
+            // 구현 상세를 흘리지 않게 CLI가 사용법(2)로 거절한다.
+            io.err(`unknown scaffold kind: ${kind}\n`);
+            return 2;
+        }
+    }
+    catch (error) {
+        // closed blueprint 거절 등 라이브러리 throw. 플래그는 통과했으나
+        // 호출 상태로 막을 일이라 실행 실패(1)가 아니라 사용법/상태(2).
+        io.err(`scaffold: ${catchMessage(error)}\n`);
+        return 2;
+    }
+    io.out(`${JSON.stringify({ ok: true, created }, null, 2)}\n`);
+    return 0;
+}
+/**
+ * `plan inspect`(추천 JSON)와 `plan approve`(status 일괄 전이)를 받는다. 결과 JSON은
+ * stdout에 내고, 거절은 같은 채널의 `{ok:false}`와 종료 코드 1이다. 알 수 없는
+ * 서브커맨드·값 없는 `--blueprint`·중복 `--blueprint`는 사용법(2).
+ *
+ * @param {string[]} rest - 서브커맨드와 플래그
+ * @param {CliIo} io - stdout/stderr 싱크
+ * @returns {number} 성공 0, 거절 1, 사용법 2
+ */
+function cmdPlan(rest, io) {
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { parseFlags } = require('./cli-flags');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { planInspect } = require('./plan-inspect');
+    // 명령을 선택한 뒤에만 기능을 읽어 다른 경로의 적재를 피한다.
+    const { approvePlan } = require('./plan-approve');
+    const command = rest[0];
+    const f = parseFlags(rest.slice(1));
+    // inspect·approve만 공개한다. 다른 서브커맨드를 받으면 사용법(2) — 런타임 거절(1)과
+    // 구분해, 없는 동사를 계획 쓰기로 착각하지 않게 한다.
+    if (command !== 'inspect' && command !== 'approve') {
+        io.err('plan: command must be inspect or approve\n');
+        return 2;
+    }
+    if (command === 'approve') {
+        // parseFlags는 중복 플래그를 마지막 값으로 덮어 조용히 삼킨다. 승인 대상이
+        // 모호해지므로 토큰을 직접 세어 사용법(2)으로 거절한다.
+        if (rest.filter((tok) => tok === '--blueprint').length > 1) {
+            io.err('plan approve: --blueprint given more than once\n');
+            return 2;
+        }
+        if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+            io.err('plan approve: --blueprint requires a directory\n');
+            return 2;
+        }
+        // --repo도 같은 이유로 거절한다: 중복이면 마지막 값이 이겨 다른 저장소를 승인할 수 있고,
+        // 값이 없으면 parseFlags가 true를 줘 cwd로 조용히 폴백한다. 둘 다 사용법(2).
+        if (rest.filter((tok) => tok === '--repo').length > 1) {
+            io.err('plan approve: --repo given more than once\n');
+            return 2;
+        }
+        if (Object.hasOwn(f, 'repo') && (typeof f.repo !== 'string' || f.repo === '')) {
+            io.err('plan approve: --repo requires a directory\n');
+            return 2;
+        }
+        const approved = approvePlan({
+            repoRoot: (f.repo || process.cwd()),
+            blueprintDir: f.blueprint,
+        });
+        io.out(`${JSON.stringify(approved, null, 2)}\n`);
+        return approved.ok ? 0 : 1;
+    }
+    // --blueprint는 선택이다. 플래그만 주고 값이 없으면 parseFlags가 true를
+    // 주므로 invalid-blueprint-dir(1)로 위장하지 않고 사용법(2)로 가른다.
+    if (Object.hasOwn(f, 'blueprint') && typeof f.blueprint !== 'string') {
+        io.err('plan inspect: --blueprint requires a directory\n');
+        return 2;
+    }
+    const result = planInspect({
+        repoRoot: (f.repo || process.cwd()),
+        epicDir: f['epic-dir'],
+        blueprintDir: f.blueprint,
+    });
+    io.out(`${JSON.stringify(result, null, 2)}\n`);
+    return result.ok ? 0 : 1;
+}
+module.exports = {
+    validate: {
+        run: cmdValidate,
+        usage: cliUsage.COMMAND_USAGE['validate'],
+    },
+    verify: {
+        run: cmdVerify,
+        usage: cliUsage.COMMAND_USAGE['verify'],
+    },
+    scaffold: {
+        run: cmdScaffold,
+        usage: cliUsage.COMMAND_USAGE['scaffold'],
+    },
+    plan: {
+        run: cmdPlan,
+        usage: cliUsage.COMMAND_USAGE['plan'],
+    },
+};

package/dist/cli-epic-command.js

@@ -0,0 +1,130 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const cliFlags = require("./cli-flags");
+const { parseFlags } = cliFlags;
+const USAGE = `usage: bouncer epic <add-domain|add-area> [--repo <dir>]\n${cliUsage.COMMAND_USAGE.epic}`;
+// 하위 명령별 허용 플래그. 목록 밖 플래그는 오타일 가능성이 커서 조용히 무시하지 않고 거절한다.
+const ALLOWED = {
+    'add-domain': ['slug', 'reason', 'yes', 'timestamp', 'repo'],
+    'add-area': ['name', 'yes', 'repo'],
+};
+// 값을 받는 필수 플래그.
+const REQUIRED = { 'add-domain': ['slug', 'reason'], 'add-area': ['name'] };
+/**
+ * 원시 argv에서 `--flag` 토큰 이름을 순서대로 모은다.
+ *
+ * @param {string[]} tokens - 하위 명령 뒤 argv
+ * @returns {string[]} 플래그 이름 목록(중복 포함)
+ */
+function flagNames(tokens) {
+    return tokens.filter((t) => t.startsWith('--')).map((t) => t.slice(2));
+}
+/**
+ * `epic` 하위 명령 argv를 검사한다. 사용법 오류(exit 2)만 여기서 거르고,
+ * `--yes` 누락은 승인 경계이므로 통과시켜 등록부를 읽기 전에 confirmation-required로 거절하게 한다.
+ *
+ * @param {string} sub - 하위 명령 이름
+ * @param {string[]} flags - 하위 명령 뒤 argv
+ * @returns {string | null} 사용법 오류 메시지(통과하면 null)
+ */
+function argvError(sub, flags) {
+    const names = flagNames(flags);
+    for (const name of names) {
+        if (!ALLOWED[sub].includes(name))
+            return `unknown flag --${name}`;
+        if (names.filter((n) => n === name).length > 1)
+            return `--${name} specified more than once`;
+    }
+    const f = parseFlags(flags);
+    for (const name of REQUIRED[sub]) {
+        if (typeof f[name] !== 'string')
+            return `--${name} is required`;
+    }
+    // slug·name은 빈 문자열이면 값이 없는 것과 같다. reason은 공백 거절을 reason 코드로
+    // 보이려고 빈 문자열도 통과시킨다.
+    for (const name of REQUIRED[sub].filter((n) => n !== 'reason')) {
+        if (f[name] === '')
+            return `--${name} is required`;
+    }
+    if (f.repo !== undefined && (typeof f.repo !== 'string' || f.repo === ''))
+        return '--repo requires a directory';
+    if (f.timestamp !== undefined && (typeof f.timestamp !== 'string' || f.timestamp === '')) {
+        return '--timestamp requires a value';
+    }
+    return null;
+}
+/**
+ * 공개 `epic` 핸들러. 등록부에 도메인 epic이나 area를 더한다. `--yes`가 사용자 명시 승인이며
+ * 없으면 등록부를 읽기 전에 거절한다. 디렉터리는 만들지 않는다(scaffold는 다음 plan이 한다).
+ *
+ * @param {string[]} rest - 하위 명령과 플래그
+ * @param {CliIo} io - stdout/stderr 싱크
+ * @returns {number} 성공 0, 등록부 거절 1, 사용법 오류 2
+ */
+function run(rest, io) {
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.out(USAGE);
+        return 0;
+    }
+    const [sub, ...flags] = rest;
+    if (sub === undefined || !Object.hasOwn(ALLOWED, sub)) {
+        io.err(`epic: unknown or missing subcommand${sub === undefined ? '' : `: ${sub}`}\n${USAGE}`);
+        return 2;
+    }
+    const bad = argvError(sub, flags);
+    if (bad !== null) {
+        io.err(`epic ${sub}: ${bad}\n${USAGE}`);
+        return 2;
+    }
+    const f = parseFlags(flags);
+    const emit = (value, code) => {
+        io.out(`${JSON.stringify(value, null, 2)}\n`);
+        return code;
+    };
+    const refuse = (reason, cause, next) => (emit({ ok: false, reason, cause, next }, 1));
+    // 승인 확인은 어떤 파일 접근보다 먼저(review accept-risk 선례).
+    if (f.yes !== true) {
+        return refuse('epic-registry-confirmation-required', `epic ${sub} needs explicit user approval`, 'Ask the user to approve, then rerun with --yes.');
+    }
+    // 승인 뒤에만 기능 모듈을 적재한다. 사용법·승인 거절이 등록부 I/O 경로를 require.cache에 남기지 않게 한다.
+    const registryLib = require('./epic-registry');
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const repoRoot = (typeof f.repo === 'string' ? f.repo : process.cwd());
+    const read = registryLib.readEpicRegistry(repoRoot);
+    if (read.status === 'missing') {
+        return refuse('epic-registry-missing', `${registryLib.REGISTRY_REL} does not exist`, 'Run `bouncer init` first.');
+    }
+    if (read.status === 'invalid') {
+        return refuse('epic-registry-invalid', read.message, `Fix ${registryLib.REGISTRY_REL} to match the format.`);
+    }
+    let result;
+    if (sub === 'add-domain') {
+        const { nowIsoKst } = require('./time');
+        // 번호 배정이 디렉터리 번호도 보므로 epics 디렉터리를 읽는다. 디렉터리 없음(ENOENT)만 빈 목록이다.
+        let dirs = [];
+        try {
+            dirs = fs.readdirSync(path.join(repoRoot, '.bouncer/context/epics'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        result = registryLib.addDomainEpic(read.registry, {
+            slug: f.slug,
+            reason: f.reason,
+            approvedAt: typeof f.timestamp === 'string' ? f.timestamp : nowIsoKst(),
+        }, dirs);
+    }
+    else {
+        result = registryLib.addArea(read.registry, f.name);
+    }
+    if (!result.ok)
+        return refuse(result.reason, result.cause, 'Adjust the input and rerun; nothing was written.');
+    // 검증을 모두 통과한 뒤 한 번만 쓴다.
+    registryLib.writeEpicRegistry(repoRoot, result.registry);
+    return emit('epic' in result
+        ? { ok: true, path: registryLib.REGISTRY_REL, epic: result.epic }
+        : { ok: true, path: registryLib.REGISTRY_REL, area: result.area }, 0);
+}
+module.exports = { run };

package/dist/cli-flags.js

@@ -0,0 +1,50 @@
+'use strict';
+/**
+ * CLI 공통 플래그 파서. 명령 모듈이 cli.ts를 require하지 못하게 여기 둔다
+ * (순환: cli.ts → 명령 모듈 → cli.ts).
+ */
+function parseFlags(rest) {
+    const flags = {};
+    // 위치 인자(scaffold kind, migrate kind)는 건너뛴다. 전부 플래그로 삼키면
+    // 핸들러가 rest[0]을 kind로 읽지 못한다.
+    for (let i = 0; i < rest.length; i += 1) {
+        const tok = rest[i];
+        if (!tok.startsWith('--'))
+            continue;
+        const key = tok.slice(2);
+        const next = rest[i + 1];
+        // 다음이 없거나 또 다른 -- 토큰이면 boolean. --yes --repo <dir> 에서
+        // '--repo'를 --yes의 값으로 소비하지 않기 위함.
+        if (next === undefined || next.startsWith('--')) {
+            flags[key] = true;
+        }
+        else {
+            flags[key] = next;
+            // 값을 소비했으니 다음 루프가 그 값을 새 플래그로 파싱하지 않는다.
+            i += 1;
+        }
+    }
+    return flags;
+}
+/**
+ * 서브커맨드 도움말 요청 여부. parseFlags는 `--help` 뒤 값을 먹고 `-h`를 무시하므로
+ * 원시 토큰을 본다. `--reason -h`처럼 직전 토큰이 `--` 플래그면 `-h`는 그 플래그의 값이다.
+ * runCli(handler 적재 전 가로채기)와 자체 help를 가진 handler가 같은 규칙을 쓰도록 한 곳에 둔다.
+ *
+ * @param {string[]} tokens - 명령 이름 뒤 원시 argv
+ * @returns {boolean} 도움말을 내면 true
+ */
+function argvRequestsHelp(tokens) {
+    for (let i = 0; i < tokens.length; i += 1) {
+        const tok = tokens[i];
+        if (tok === '--help')
+            return true;
+        if (tok === '-h') {
+            const prev = i > 0 ? tokens[i - 1] : undefined;
+            if (prev === undefined || !prev.startsWith('--'))
+                return true;
+        }
+    }
+    return false;
+}
+module.exports = { parseFlags, argvRequestsHelp };