gitifact 0.8.5 → 0.9.0

package/dist/i18n/ko/docs/writing.md

@@ -1,9 +1,9 @@
 ---
 title: 문서 문체
-description: 지침·요구사항·설계·결정기록에 공통으로 적용하는 문체, 본문과 결정기록의 구분, 인용·Alert·다이어그램, AI 슬롭 제거
+description: 요구사항·설계·결정기록에 공통으로 적용하는 문체, 본문과 결정기록의 구분, 인용·Alert·다이어그램, AI 슬롭 제거
 ---
 
-프로젝트 지침·요구사항·설계에 모두 적용한다. 문서는 CLI 표시 언어와 무관하게 프로젝트의 언어로 쓴다. 본문은 '~한다', '~이다'로 통일하고 제목은 내용을 나타내는 명사형으로 쓴다. 화면 문구·인용·코드의 표현은 유지한다.
+요구사항·설계에 모두 적용한다. 문서는 CLI 표시 언어와 무관하게 프로젝트의 언어로 쓴다. 본문은 '~한다', '~이다'로 통일하고 제목은 내용을 나타내는 명사형으로 쓴다. 화면 문구·인용·코드의 표현은 유지한다.
 
 ## 서술과 구성
 
@@ -24,13 +24,13 @@ description: 지침·요구사항·설계·결정기록에 공통으로 적용
 
 본문에는 지금 유효한 동작과 규칙만 쓴다. '전에는 …했는데 …라서 바꿨다', 바꾼 날짜와 계기, 옛 방식, 측정해 가며 고른 과정은 본문에 두지 않고 결정기록에 쓴다(`gitifact guide show records`). 읽는 사람은 이유를 `gitifact records list --doc <ID>`로, 옛 원문을 `gitifact specs show <ID> --ref <커밋>`으로 본다.
 
-문서를 고칠 때는 바뀐 문장을 고쳐 쓰고 옛 동작을 설명하는 문장을 덧붙이지 않는다. 지켜야 할 결정은 본문에 규칙으로 쓰고, 그 맥락과 검토한 대안은 결정기록에 둔다. 설계나 지침에 결정 표를 따로 두지 않는다.
+문서를 고칠 때는 바뀐 문장을 고쳐 쓰고 옛 동작을 설명하는 문장을 덧붙이지 않는다. 지켜야 할 결정은 본문에 규칙으로 쓰고, 그 맥락과 검토한 대안은 결정기록에 둔다. 설계에 결정 표를 따로 두지 않는다.
 
 ## 인용과 Alert
 
 일반 인용구는 다른 문서나 발언을 인용할 때 쓴다. 문장 속에 묻히면 다음 작업자가 놓치기 쉬운 내용은 [GitHub Alert 문법](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)으로 따로 둔다.
 
-| 종류 | 쓰는 자리 | 설계·지침의 예 |
+| 종류 | 쓰는 자리 | 설계의 예 |
 | :--- | :--- | :--- |
 | `IMPORTANT` | 깨면 안 되는 불변 조건, 작업 전에 알아야 할 필수 조건 | 원본 파일을 바꾸지 않는다, 실패를 조용히 삼키지 않는다 |
 | `WARNING` | 어기면 보안 문제나 잘못된 동작으로 이어지는 조건 | 인증 없이 열린 경로의 범위를 넓히지 않는다 |

package/dist/launcher/cli.mjs

@@ -0,0 +1,77 @@
+// Gitifact launcher, written by `gitifact init` and `gitifact update`; do not edit, the next update rewrites it.
+// It runs the Gitifact release this project is on (`cli` in ../config.json): `node .gitifact/bin/cli.mjs <command>`.
+// The release is kept once per computer in the user's cache, fetched from the npm registry the first time and checked
+// against the registry's integrity. GITIFACT_PACKAGE names a local package file to use instead (an unpublished build).
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, normalize, sep } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+
+const fail = message => { process.stderr.write('gitifact launcher: ' + message + '\n'); process.exit(1); };
+
+let version;
+try { version = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'config.json'), 'utf8')).cli; }
+catch { fail('cannot read .gitifact/config.json next to this launcher.'); }
+if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) fail('.gitifact/config.json has no valid "cli" version.');
+
+// The same per-user cache folder the CLI keeps its update check in.
+const env = process.env; const home = homedir();
+const cacheRoot = env.GITIFACT_CACHE_DIR || (process.platform === 'win32' ? join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'gitifact')
+  : process.platform === 'darwin' ? join(home, 'Library', 'Caches', 'gitifact') : join(env.XDG_CACHE_HOME || join(home, '.cache'), 'gitifact'));
+const releases = join(cacheRoot, 'cli');
+const main = join(releases, version, 'package', 'dist', 'main.js');
+
+/** The files of a gzipped tar, by path: enough of ustar, pax and GNU long names for an npm package. */
+function untar(gzipped) {
+  const data = gunzipSync(gzipped); const files = new Map();
+  const text = (start, length) => data.subarray(start, start + length).toString('utf8').replace(/\0.*$/s, '');
+  let offset = 0; let longName;
+  while (offset + 512 <= data.length) {
+    if (data[offset] === 0) break;
+    const size = parseInt(text(offset + 124, 12).trim() || '0', 8); const type = String.fromCharCode(data[offset + 156] || 48);
+    const body = data.subarray(offset + 512, offset + 512 + size);
+    let name = longName ?? ((text(offset + 345, 155) ? text(offset + 345, 155) + '/' : '') + text(offset, 100)); longName = undefined;
+    if (type === 'x') { const path = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8')); if (path) longName = path[1]; }
+    else if (type === 'L') longName = body.toString('utf8').replace(/\0.*$/s, '');
+    else if (type === '0' || type === '7') files.set(name, body);
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
+/** Unpacks a package into the cache as `<version>/package`, all at once so a half-written release is never run. */
+function unpack(tarball) {
+  mkdirSync(releases, { recursive: true });
+  const staging = mkdtempSync(join(releases, '.tmp-'));
+  try {
+    for (const [name, body] of untar(tarball)) {
+      const path = normalize(join(staging, name));
+      if (!path.startsWith(staging + sep)) throw new Error('the package holds a path outside itself: ' + name);
+      mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, body);
+    }
+    const unpacked = JSON.parse(readFileSync(join(staging, 'package', 'package.json'), 'utf8'));
+    if (unpacked.name !== 'gitifact' || unpacked.version !== version) throw new Error('the package is ' + unpacked.name + '@' + unpacked.version + ', not gitifact@' + version + '.');
+    try { renameSync(staging, join(releases, version)); }
+    catch (error) { if (!existsSync(main)) throw error; }
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+}
+
+async function fetchRelease() {
+  const registry = (env.npm_config_registry || 'https://registry.npmjs.org').replace(/\/+$/, '');
+  process.stderr.write('gitifact launcher: fetching gitifact@' + version + ' once for this computer…\n');
+  const manifest = await fetch(registry + '/gitifact/' + version).then(r => r.ok ? r.json() : fail('the registry has no gitifact@' + version + ' (' + r.status + ').'));
+  const { tarball, integrity } = manifest.dist ?? {};
+  if (!tarball || !/^sha512-/.test(integrity ?? '')) fail('the registry answer for gitifact@' + version + ' has no sha512 integrity.');
+  const bytes = Buffer.from(await fetch(tarball).then(r => r.ok ? r.arrayBuffer() : fail('could not download ' + tarball + ' (' + r.status + ').')));
+  if ('sha512-' + createHash('sha512').update(bytes).digest('base64') !== integrity) fail('the downloaded package does not match the registry integrity.');
+  return bytes;
+}
+
+if (!existsSync(main)) {
+  try { unpack(env.GITIFACT_PACKAGE ? readFileSync(env.GITIFACT_PACKAGE) : await fetchRelease()); }
+  catch (error) { fail('could not prepare gitifact@' + version + ': ' + (error?.message ?? error)); }
+}
+const run = spawnSync(process.execPath, [main, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(run.status ?? 1);