egehan 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +79 -2
  3. package/assets/dictionary/narratives.en.json +660 -0
  4. package/assets/dictionary/narratives.tr.json +660 -0
  5. package/assets/schema/egehan-report.schema.json +354 -0
  6. package/assets/spec/rules.json +272 -0
  7. package/assets/templates/egehan-book.html +2027 -0
  8. package/assets/templates/hook.sh +41 -0
  9. package/dist/artifacts.d.ts +21 -0
  10. package/dist/artifacts.js +32 -0
  11. package/dist/capsule/capsule.d.ts +35 -0
  12. package/dist/capsule/capsule.js +123 -0
  13. package/dist/capsule/storage.d.ts +15 -0
  14. package/dist/capsule/storage.js +52 -0
  15. package/dist/cli/commands/capsule.d.ts +20 -0
  16. package/dist/cli/commands/capsule.js +94 -0
  17. package/dist/cli/commands/generate.d.ts +23 -0
  18. package/dist/cli/commands/generate.js +47 -0
  19. package/dist/cli/commands/hook.d.ts +14 -0
  20. package/dist/cli/commands/hook.js +120 -0
  21. package/dist/cli/commands/init.d.ts +16 -0
  22. package/dist/cli/commands/init.js +92 -0
  23. package/dist/cli/commands/stats.d.ts +14 -0
  24. package/dist/cli/commands/stats.js +112 -0
  25. package/dist/cli/main.d.ts +3 -0
  26. package/dist/cli/main.js +167 -0
  27. package/dist/cli/output.d.ts +26 -0
  28. package/dist/cli/output.js +87 -0
  29. package/dist/cli/prompt.d.ts +21 -0
  30. package/dist/cli/prompt.js +63 -0
  31. package/dist/config/config.d.ts +51 -0
  32. package/dist/config/config.js +160 -0
  33. package/dist/detect/projectType.d.ts +34 -0
  34. package/dist/detect/projectType.js +95 -0
  35. package/dist/engine/buildReport.d.ts +32 -0
  36. package/dist/engine/buildReport.js +188 -0
  37. package/dist/engine/chapters.d.ts +20 -0
  38. package/dist/engine/chapters.js +33 -0
  39. package/dist/engine/classifier.d.ts +21 -0
  40. package/dist/engine/classifier.js +119 -0
  41. package/dist/engine/conventional.d.ts +15 -0
  42. package/dist/engine/conventional.js +137 -0
  43. package/dist/engine/datetime.d.ts +47 -0
  44. package/dist/engine/datetime.js +100 -0
  45. package/dist/engine/milestones.d.ts +6 -0
  46. package/dist/engine/milestones.js +109 -0
  47. package/dist/engine/narrator.d.ts +71 -0
  48. package/dist/engine/narrator.js +189 -0
  49. package/dist/engine/prepare.d.ts +36 -0
  50. package/dist/engine/prepare.js +46 -0
  51. package/dist/engine/privacy.d.ts +45 -0
  52. package/dist/engine/privacy.js +110 -0
  53. package/dist/engine/pulse.d.ts +17 -0
  54. package/dist/engine/pulse.js +205 -0
  55. package/dist/engine/templating.d.ts +40 -0
  56. package/dist/engine/templating.js +64 -0
  57. package/dist/engine/types.d.ts +205 -0
  58. package/dist/engine/types.js +9 -0
  59. package/dist/git/logReader.d.ts +37 -0
  60. package/dist/git/logReader.js +133 -0
  61. package/dist/git/repository.d.ts +14 -0
  62. package/dist/git/repository.js +61 -0
  63. package/dist/git/runGit.d.ts +21 -0
  64. package/dist/git/runGit.js +74 -0
  65. package/dist/hooks/block.d.ts +27 -0
  66. package/dist/hooks/block.js +62 -0
  67. package/dist/hooks/manager.d.ts +47 -0
  68. package/dist/hooks/manager.js +153 -0
  69. package/dist/index.d.ts +34 -0
  70. package/dist/index.js +26 -0
  71. package/dist/pipeline.d.ts +35 -0
  72. package/dist/pipeline.js +80 -0
  73. package/dist/renderers/html.d.ts +6 -0
  74. package/dist/renderers/html.js +117 -0
  75. package/dist/renderers/markdown.d.ts +4 -0
  76. package/dist/renderers/markdown.js +168 -0
  77. package/dist/spec/assets.d.ts +14 -0
  78. package/dist/spec/assets.js +98 -0
  79. package/dist/spec/dictionary.d.ts +100 -0
  80. package/dist/spec/dictionary.js +39 -0
  81. package/dist/spec/rules.d.ts +191 -0
  82. package/dist/spec/rules.js +15 -0
  83. package/dist/version.d.ts +2 -0
  84. package/dist/version.js +20 -0
  85. package/package.json +55 -4
@@ -0,0 +1,92 @@
1
+ import { existsSync, writeFileSync } from 'node:fs';
2
+ import { createInterface } from 'node:readline/promises';
3
+ import { relative } from 'node:path';
4
+ import { stdin, stdout } from 'node:process';
5
+ import { configExists, configPath, defaultConfig, FORMATS, serializeConfig, TONES, } from '../../config/config.js';
6
+ import { availableLanguages } from '../../spec/dictionary.js';
7
+ import { loadRules } from '../../spec/rules.js';
8
+ import { isGitRepository, readRepositoryInfo } from '../../git/repository.js';
9
+ import { info, success, theme, warn } from '../output.js';
10
+ export async function runInit(options) {
11
+ const rules = loadRules();
12
+ const gitContext = { cwd: options.cwd, rules };
13
+ const root = isGitRepository(gitContext) ? readRepositoryInfo(gitContext).root : options.cwd;
14
+ const path = configPath(root, rules);
15
+ if (configExists(root, rules) && !options.force) {
16
+ warn(`${relative(options.cwd, path) || path} already exists. Pass --force to replace it.`);
17
+ return;
18
+ }
19
+ const base = defaultConfig(rules);
20
+ const suggestedName = isGitRepository(gitContext) ? readRepositoryInfo(gitContext).name : null;
21
+ if (options.yes) {
22
+ write(path, { ...base, projectName: suggestedName }, options.cwd);
23
+ return;
24
+ }
25
+ const rl = createInterface({ input: stdin, output: stdout });
26
+ try {
27
+ info('');
28
+ info(theme.heading('Egehan'));
29
+ info(theme.muted('A few questions, then your chronicle writes itself after every commit.'));
30
+ info('');
31
+ const projectName = await askText(rl, 'Project name', suggestedName ?? '');
32
+ const language = (await askChoice(rl, 'Language', availableLanguages(), base.language));
33
+ const tone = (await askChoice(rl, 'Narrative tone', TONES, base.tone));
34
+ const format = (await askChoice(rl, 'Output', [...FORMATS], base.format));
35
+ const redactEmails = await askYesNo(rl, 'Redact author e-mail addresses', base.redactEmails);
36
+ info('');
37
+ info(theme.muted('A dedication is optional. It is written at the top of the generated files,'));
38
+ info(theme.muted('so treat it as something the repository publishes. Leave blank to skip.'));
39
+ const dedication = await askText(rl, 'Dedication', '');
40
+ write(path, {
41
+ ...base,
42
+ projectName: projectName === '' ? suggestedName : projectName,
43
+ dedication: dedication === '' ? null : dedication,
44
+ language,
45
+ tone,
46
+ format,
47
+ redactEmails,
48
+ }, options.cwd);
49
+ }
50
+ finally {
51
+ rl.close();
52
+ }
53
+ }
54
+ function write(path, config, cwd) {
55
+ const existed = existsSync(path);
56
+ writeFileSync(path, serializeConfig(config), 'utf8');
57
+ success(`${existed ? 'Replaced' : 'Created'} ${relative(cwd, path) || path}`);
58
+ info('');
59
+ info(` ${theme.accent('egehan generate')} ${theme.muted('write the chronicle')}`);
60
+ info(` ${theme.accent('egehan stats')} ${theme.muted('see the Developer Pulse')}`);
61
+ info('');
62
+ }
63
+ async function askText(rl, label, fallback) {
64
+ const suffix = fallback === '' ? '' : theme.muted(` (${fallback})`);
65
+ const answer = (await rl.question(`${label}${suffix}: `)).trim();
66
+ return answer === '' ? fallback : answer;
67
+ }
68
+ async function askChoice(rl, label, choices, fallback) {
69
+ const rendered = choices.map((choice) => (choice === fallback ? theme.accent(choice) : choice)).join(' / ');
70
+ for (;;) {
71
+ const answer = (await rl.question(`${label} [${rendered}]: `)).trim().toLowerCase();
72
+ if (answer === '')
73
+ return fallback;
74
+ if (choices.includes(answer))
75
+ return answer;
76
+ warn(`Pick one of: ${choices.join(', ')}`);
77
+ }
78
+ }
79
+ async function askYesNo(rl, label, fallback) {
80
+ const hint = fallback ? `${theme.accent('Y')}/n` : `y/${theme.accent('N')}`;
81
+ for (;;) {
82
+ const answer = (await rl.question(`${label} [${hint}]: `)).trim().toLowerCase();
83
+ if (answer === '')
84
+ return fallback;
85
+ if (['y', 'yes'].includes(answer))
86
+ return true;
87
+ if (['n', 'no'].includes(answer))
88
+ return false;
89
+ warn('Answer y or n.');
90
+ }
91
+ }
92
+ //# sourceMappingURL=init.js.map
@@ -0,0 +1,14 @@
1
+ /**
2
+ * `egehan stats` — the Developer Pulse, in the terminal.
3
+ *
4
+ * Deliberately a read-only command that writes no files. It is the thing somebody runs out of
5
+ * curiosity, and a command run out of curiosity must never leave anything behind.
6
+ */
7
+ export interface StatsOptions {
8
+ readonly cwd: string;
9
+ readonly since: string | null;
10
+ readonly until: string | null;
11
+ readonly overrides: Record<string, unknown>;
12
+ }
13
+ export declare function runStats(options: StatsOptions): void;
14
+ //# sourceMappingURL=stats.d.ts.map
@@ -0,0 +1,112 @@
1
+ import { loadDictionary } from '../../spec/dictionary.js';
2
+ import { produceReport } from '../../pipeline.js';
3
+ import { info, theme, visibleWidth } from '../output.js';
4
+ const BLOCKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
5
+ const PANEL_WIDTH = 64;
6
+ export function runStats(options) {
7
+ const { report } = produceReport({
8
+ cwd: options.cwd,
9
+ since: options.since,
10
+ until: options.until,
11
+ overrides: options.overrides,
12
+ });
13
+ const dictionary = loadDictionary(report.config.language);
14
+ render(report, dictionary);
15
+ }
16
+ function render(report, dictionary) {
17
+ const { pulse } = report;
18
+ const labels = dictionary.pulse.labels;
19
+ const chronotype = dictionary.pulse.chronotypes[pulse.chronotype];
20
+ info('');
21
+ info(frameTop());
22
+ info(frameLine(`${theme.heading(report.project.name)} ${theme.muted('— ' + dictionary.pulse.title)}`));
23
+ info(frameSeparator());
24
+ info(frameLine(wrapText(pulse.narrative, PANEL_WIDTH - 4)[0] ?? ''));
25
+ for (const line of wrapText(pulse.narrative, PANEL_WIDTH - 4).slice(1)) {
26
+ info(frameLine(line));
27
+ }
28
+ info(frameSeparator());
29
+ const rows = [
30
+ [labels['chronotype'] ?? '', `${chronotype?.icon ?? ''} ${pulse.chronotypeLabel}`],
31
+ [labels['busiestDay'] ?? '', dictionary.locale.weekdays[pulse.busiestWeekday] ?? ''],
32
+ [labels['busiestHour'] ?? '', `${pad(pulse.busiestHour)}:00`],
33
+ [labels['creationRatio'] ?? '', `${Math.round(pulse.creationRatio * 100)}%`],
34
+ [labels['avgCommitSize'] ?? '', `${pulse.avgChangedLines} ${dictionary.units.line.other}`.trim()],
35
+ [
36
+ labels['longestStreak'] ?? '',
37
+ pulse.longestStreak.days > 0
38
+ ? `${pulse.longestStreak.days} (${pulse.longestStreak.from} → ${pulse.longestStreak.to})`
39
+ : '—',
40
+ ],
41
+ [labels['totalCommits'] ?? '', String(report.totals.commits)],
42
+ [labels['totalAuthors'] ?? '', String(report.totals.authors)],
43
+ [labels['projectAge'] ?? '', `${report.range.days} ${dictionary.ui['daysLabel'] ?? ''}`.trim()],
44
+ ];
45
+ const widest = Math.max(...rows.map(([label]) => visibleWidth(label)));
46
+ for (const [label, value] of rows) {
47
+ info(frameLine(`${theme.muted(label.padEnd(widest))} ${theme.value(value)}`));
48
+ }
49
+ info(frameSeparator());
50
+ info(frameLine(theme.muted(labels['hourDistribution'] ?? '')));
51
+ info(frameLine(histogram(pulse.hourHistogram)));
52
+ info(frameLine(theme.muted('0 3 6 9 12 15 18 21')));
53
+ info(frameSeparator());
54
+ info(frameLine(theme.muted(labels['weekdayDistribution'] ?? '')));
55
+ info(frameLine(histogram(pulse.weekdayHistogram, 3)));
56
+ info(frameLine(theme.muted(dictionary.locale.weekdaysShort.map((day) => day.slice(0, 3).padEnd(3)).join(''))));
57
+ info(frameSeparator());
58
+ const categories = Object.entries(report.totals.byCategory)
59
+ .filter(([, count]) => count > 0)
60
+ .map(([category, count]) => {
61
+ const narratives = dictionary.categories[category];
62
+ return `${narratives?.icon ?? ''}${theme.value(String(count))}`;
63
+ });
64
+ info(frameLine(categories.join(' ')));
65
+ info(frameBottom());
66
+ info('');
67
+ }
68
+ function histogram(values, cellWidth = 1) {
69
+ const peak = Math.max(1, ...values);
70
+ return values
71
+ .map((count) => {
72
+ if (count === 0)
73
+ return ' '.repeat(cellWidth);
74
+ const level = Math.ceil((count / peak) * BLOCKS.length) - 1;
75
+ const block = BLOCKS[Math.max(0, Math.min(BLOCKS.length - 1, level))] ?? ' ';
76
+ return theme.accent(block.padEnd(cellWidth));
77
+ })
78
+ .join('');
79
+ }
80
+ /** Word wrap that counts visible characters, so styled text does not break the frame. */
81
+ function wrapText(text, width) {
82
+ const words = text.split(/\s+/);
83
+ const lines = [];
84
+ let line = '';
85
+ for (const word of words) {
86
+ if (line === '') {
87
+ line = word;
88
+ }
89
+ else if (visibleWidth(`${line} ${word}`) <= width) {
90
+ line = `${line} ${word}`;
91
+ }
92
+ else {
93
+ lines.push(line);
94
+ line = word;
95
+ }
96
+ }
97
+ if (line !== '')
98
+ lines.push(line);
99
+ return lines.length > 0 ? lines : [''];
100
+ }
101
+ const frameTop = () => theme.muted(`╭${'─'.repeat(PANEL_WIDTH - 2)}╮`);
102
+ const frameBottom = () => theme.muted(`╰${'─'.repeat(PANEL_WIDTH - 2)}╯`);
103
+ const frameSeparator = () => theme.muted(`├${'─'.repeat(PANEL_WIDTH - 2)}┤`);
104
+ function frameLine(content) {
105
+ const inner = PANEL_WIDTH - 4;
106
+ const padding = Math.max(0, inner - visibleWidth(content));
107
+ return `${theme.muted('│')} ${content}${' '.repeat(padding)} ${theme.muted('│')}`;
108
+ }
109
+ function pad(value) {
110
+ return String(value).padStart(2, '0');
111
+ }
112
+ //# sourceMappingURL=stats.js.map
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=main.d.ts.map
@@ -0,0 +1,167 @@
1
+ #!/usr/bin/env node
2
+ import { Command, InvalidArgumentError } from 'commander';
3
+ import { runCapsule } from './commands/capsule.js';
4
+ import { runGenerate } from './commands/generate.js';
5
+ import { runHook } from './commands/hook.js';
6
+ import { runInit } from './commands/init.js';
7
+ import { runStats } from './commands/stats.js';
8
+ import { fail, info, theme } from './output.js';
9
+ import { ConfigError, FORMATS, TONES } from '../config/config.js';
10
+ import { availableLanguages } from '../spec/dictionary.js';
11
+ import { CapsuleError } from '../capsule/capsule.js';
12
+ import { PromptError } from './prompt.js';
13
+ import { EmptyHistoryError, NoCommitsError, NotARepositoryError } from '../pipeline.js';
14
+ import { GitError } from '../git/runGit.js';
15
+ import { packageVersion } from '../version.js';
16
+ function overridesFrom(flags) {
17
+ const overrides = {};
18
+ if (flags.language !== undefined)
19
+ overrides['language'] = flags.language;
20
+ if (flags.tone !== undefined)
21
+ overrides['tone'] = flags.tone;
22
+ if (flags.anonymize === true)
23
+ overrides['anonymizeAuthors'] = true;
24
+ // commander maps --no-redact-emails to redactEmails === false.
25
+ if (flags.redactEmails === false)
26
+ overrides['redactEmails'] = false;
27
+ if (flags.includeMerges === true)
28
+ overrides['includeMergeCommits'] = true;
29
+ if (flags.projectName !== undefined)
30
+ overrides['projectName'] = flags.projectName;
31
+ return overrides;
32
+ }
33
+ function withSharedFlags(command) {
34
+ return command
35
+ .option('--since <ref>', 'start from a tag, revision or date (v1.0.0, HEAD~50, 2025-01-01)')
36
+ .option('--until <ref>', 'stop at a tag, revision or date')
37
+ .option('--language <code>', `narration language (${availableLanguages().join(', ')})`)
38
+ .option('--tone <tone>', `narrative tone (${TONES.join(', ')})`)
39
+ .option('--project-name <name>', 'override the project name')
40
+ .option('--anonymize', 'replace author names with Developer #1, #2, …')
41
+ .option('--no-redact-emails', 'keep author e-mail addresses in the output')
42
+ .option('--include-merges', 'narrate merge commits too');
43
+ }
44
+ const program = new Command();
45
+ program
46
+ .name('egehan')
47
+ .description("Turn a project's git history into a living chronicle — offline, deterministic, no API key.")
48
+ .version(packageVersion(), '-v, --version')
49
+ .showHelpAfterError('(run `egehan --help` for the available commands)');
50
+ withSharedFlags(program
51
+ .command('generate', { isDefault: true })
52
+ .description('write the chronicle for this repository')
53
+ .option('-o, --output <dir>', 'directory to write into (default: the repository root)')
54
+ .option('-f, --format <format>', `output format (${FORMATS.join(', ')})`, parseFormat)
55
+ .option('-q, --quiet', 'write the files and print nothing')).action((flags) => {
56
+ runGenerate({
57
+ cwd: process.cwd(),
58
+ since: flags.since ?? null,
59
+ until: flags.until ?? null,
60
+ output: flags.output ?? null,
61
+ format: flags.format ?? null,
62
+ overrides: overridesFrom(flags),
63
+ quiet: flags.quiet === true,
64
+ });
65
+ });
66
+ withSharedFlags(program.command('stats').description('show the Developer Pulse without writing any files')).action((flags) => {
67
+ runStats({
68
+ cwd: process.cwd(),
69
+ since: flags.since ?? null,
70
+ until: flags.until ?? null,
71
+ overrides: overridesFrom(flags),
72
+ });
73
+ });
74
+ program
75
+ .command('init')
76
+ .description('create .egehanrc.json interactively')
77
+ .option('-y, --yes', 'accept the defaults without asking')
78
+ .option('--force', 'replace an existing .egehanrc.json')
79
+ .action(async (flags) => {
80
+ await runInit({ cwd: process.cwd(), yes: flags.yes === true, force: flags.force === true });
81
+ });
82
+ program
83
+ .command('capsule')
84
+ .description('seal a passphrase-protected message into the chronicle, or open one')
85
+ .option('-m, --message <text>', 'the message to seal')
86
+ .option('--message-file <path>', 'read the message from a file instead')
87
+ .option('-d, --unlock-date <date>', 'the date the countdown runs to (YYYY-MM-DD)')
88
+ .option('-a, --author <name>', 'who the message is from')
89
+ .option('--hint <text>', 'a passphrase hint — stored in clear text, and it travels with the file')
90
+ .option('--file <path>', 'where the capsule lives (default: capsule.egehan.json)')
91
+ .option('--open', 'decrypt an existing capsule and print it')
92
+ .option('--force', 'replace an existing capsule, losing the message inside it')
93
+ // There is no --passphrase flag on purpose: a secret on the command line lands in the shell
94
+ // history and in the process list. See src/cli/prompt.ts.
95
+ .addHelpText('after', '\nThe passphrase is always typed at a prompt, never passed as a flag.\n' +
96
+ 'Set EGEHAN_PASSPHRASE for automation; be aware every child process inherits it.')
97
+ .action(async (flags) => {
98
+ await runCapsule({
99
+ cwd: process.cwd(),
100
+ message: flags.message ?? null,
101
+ messageFile: flags.messageFile ?? null,
102
+ unlockDate: flags.unlockDate ?? null,
103
+ author: flags.author ?? null,
104
+ hint: flags.hint ?? null,
105
+ file: flags.file ?? null,
106
+ open: flags.open === true,
107
+ force: flags.force === true,
108
+ });
109
+ });
110
+ program
111
+ .command('hook')
112
+ .argument('<action>', 'install, uninstall or status')
113
+ .description('keep the chronicle updating after every commit and merge')
114
+ .addHelpText('after', '\nThe installed hook runs in the background and never stages or commits anything.\n' +
115
+ 'It installs alongside Husky; with Lefthook it prints the configuration to add instead.\n' +
116
+ 'EGEHAN_SKIP_HOOK=1 switches it off for a single command.')
117
+ .action((action) => {
118
+ if (action !== 'install' && action !== 'uninstall' && action !== 'status') {
119
+ throw new InvalidArgumentError('Expected one of: install, uninstall, status');
120
+ }
121
+ runHook({ cwd: process.cwd(), action: action });
122
+ });
123
+ function parseFormat(value) {
124
+ if (!FORMATS.includes(value)) {
125
+ throw new InvalidArgumentError(`Expected one of: ${FORMATS.join(', ')}`);
126
+ }
127
+ return value;
128
+ }
129
+ /**
130
+ * Error reporting.
131
+ *
132
+ * Expected failures — not a repository, no commits, a bad config — print one clear sentence and
133
+ * exit 1. Only genuinely unexpected errors print a stack trace, because a stack trace shown for a
134
+ * predictable situation teaches users that the tool is broken when it is merely being used in a
135
+ * directory that is not a git repository.
136
+ */
137
+ function reportError(error) {
138
+ if (error instanceof NotARepositoryError ||
139
+ error instanceof NoCommitsError ||
140
+ error instanceof EmptyHistoryError ||
141
+ error instanceof ConfigError ||
142
+ error instanceof CapsuleError ||
143
+ error instanceof PromptError ||
144
+ error instanceof GitError) {
145
+ fail(error.message);
146
+ process.exit(1);
147
+ }
148
+ if (error instanceof Error) {
149
+ fail(error.message);
150
+ if (process.env['EGEHAN_DEBUG'] === '1' && error.stack !== undefined) {
151
+ info(theme.muted(error.stack));
152
+ }
153
+ else {
154
+ info(theme.muted('Set EGEHAN_DEBUG=1 for a stack trace.'));
155
+ }
156
+ process.exit(1);
157
+ }
158
+ fail(String(error));
159
+ process.exit(1);
160
+ }
161
+ try {
162
+ await program.parseAsync(process.argv);
163
+ }
164
+ catch (error) {
165
+ reportError(error);
166
+ }
167
+ //# sourceMappingURL=main.js.map
@@ -0,0 +1,26 @@
1
+ import { styleText } from 'node:util';
2
+ /**
3
+ * Terminal output.
4
+ *
5
+ * Colour comes from `node:util.styleText`, which has been in Node since 20.12 — so the published
6
+ * CLI needs no colour library and therefore cannot be broken by one. Styling is suppressed when
7
+ * the stream is not a TTY, when `NO_COLOR` is set, or when `TERM=dumb`, which together cover
8
+ * piping to a file, CI logs and the git hook that runs this tool in the background.
9
+ */
10
+ type Style = Parameters<typeof styleText>[0];
11
+ export declare function paint(style: Style, text: string): string;
12
+ export declare const theme: {
13
+ readonly heading: (text: string) => string;
14
+ readonly accent: (text: string) => string;
15
+ readonly muted: (text: string) => string;
16
+ readonly warn: (text: string) => string;
17
+ readonly error: (text: string) => string;
18
+ readonly value: (text: string) => string;
19
+ };
20
+ export declare function info(message: string): void;
21
+ export declare function success(message: string): void;
22
+ export declare function warn(message: string): void;
23
+ export declare function fail(message: string): void;
24
+ export declare function visibleWidth(text: string): number;
25
+ export {};
26
+ //# sourceMappingURL=output.d.ts.map
@@ -0,0 +1,87 @@
1
+ import { styleText } from 'node:util';
2
+ const colorEnabled = (() => {
3
+ if (process.env['NO_COLOR'] !== undefined && process.env['NO_COLOR'] !== '')
4
+ return false;
5
+ if (process.env['FORCE_COLOR'] !== undefined && process.env['FORCE_COLOR'] !== '')
6
+ return true;
7
+ if (process.env['TERM'] === 'dumb')
8
+ return false;
9
+ return process.stdout.isTTY === true;
10
+ })();
11
+ export function paint(style, text) {
12
+ return colorEnabled ? styleText(style, text) : text;
13
+ }
14
+ export const theme = {
15
+ heading: (text) => paint(['bold'], text),
16
+ accent: (text) => paint(['green'], text),
17
+ muted: (text) => paint(['dim'], text),
18
+ warn: (text) => paint(['yellow'], text),
19
+ error: (text) => paint(['red', 'bold'], text),
20
+ value: (text) => paint(['cyan', 'bold'], text),
21
+ };
22
+ export function info(message) {
23
+ process.stdout.write(`${message}\n`);
24
+ }
25
+ export function success(message) {
26
+ process.stdout.write(`${theme.accent('✔')} ${message}\n`);
27
+ }
28
+ export function warn(message) {
29
+ process.stderr.write(`${theme.warn('!')} ${message}\n`);
30
+ }
31
+ export function fail(message) {
32
+ process.stderr.write(`${theme.error('✖')} ${message}\n`);
33
+ }
34
+ /**
35
+ * Column width of a string as a terminal will actually render it.
36
+ *
37
+ * Counting characters is not enough: an emoji occupies two columns, a variation selector occupies
38
+ * none but widens the symbol before it, and combining marks occupy none at all. Getting this wrong
39
+ * is visible — the category icons pushed the right-hand border of the stats panel one column out,
40
+ * on every line that had one. A dependency for this would be a dependency in a CLI that promises
41
+ * not to have any, and the ranges below cover what this tool actually prints.
42
+ */
43
+ const WIDE_RANGES = [
44
+ [0x1100, 0x115f],
45
+ [0x2329, 0x232a],
46
+ [0x2e80, 0x303e],
47
+ [0x3041, 0x33ff],
48
+ [0x3400, 0x4dbf],
49
+ [0x4e00, 0x9fff],
50
+ [0xa000, 0xa4cf],
51
+ [0xac00, 0xd7a3],
52
+ [0xf900, 0xfaff],
53
+ [0xfe30, 0xfe6f],
54
+ [0xff00, 0xff60],
55
+ [0xffe0, 0xffe6],
56
+ [0x1f000, 0x1f02f],
57
+ [0x1f0a0, 0x1f0ff],
58
+ [0x1f100, 0x1f1ff],
59
+ [0x1f200, 0x1f2ff],
60
+ [0x1f300, 0x1f9ff],
61
+ [0x1fa00, 0x1faff],
62
+ [0x20000, 0x3fffd],
63
+ ];
64
+ const isWide = (codePoint) => WIDE_RANGES.some(([start, end]) => codePoint >= start && codePoint <= end);
65
+ export function visibleWidth(text) {
66
+ const plain = text.replace(/\u001b\[[0-9;]*m/g, '');
67
+ let width = 0;
68
+ for (const character of plain) {
69
+ const codePoint = character.codePointAt(0);
70
+ if (codePoint === undefined)
71
+ continue;
72
+ // U+FE0F (variation selector-16) renders the preceding symbol in emoji form, which is two
73
+ // columns wide: the selector itself takes none, so it contributes the missing column.
74
+ if (codePoint === 0xfe0f) {
75
+ width += 1;
76
+ continue;
77
+ }
78
+ // Zero-width joiner, other variation selectors and combining marks occupy no columns.
79
+ if (codePoint === 0x200d || (codePoint >= 0xfe00 && codePoint <= 0xfe0e))
80
+ continue;
81
+ if (codePoint >= 0x0300 && codePoint <= 0x036f)
82
+ continue;
83
+ width += isWide(codePoint) ? 2 : 1;
84
+ }
85
+ return width;
86
+ }
87
+ //# sourceMappingURL=output.js.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Reading a passphrase.
3
+ *
4
+ * There is deliberately **no `--passphrase` flag**. A secret passed on the command line lands in
5
+ * the shell's history file and is visible to every other process on the machine through the
6
+ * process list — for a passphrase that is meant to hold for eighteen years, that is not a trade
7
+ * worth making for a few saved keystrokes.
8
+ *
9
+ * `EGEHAN_PASSPHRASE` exists for automation. It is better than a flag and still worse than
10
+ * typing: an environment variable is inherited by every child process. The CLI says so when it
11
+ * uses one.
12
+ */
13
+ export declare const PASSPHRASE_ENV = "EGEHAN_PASSPHRASE";
14
+ export declare class PromptError extends Error {
15
+ constructor(message: string);
16
+ }
17
+ export declare function passphraseFromEnvironment(): string | null;
18
+ /** Asks a question with the typed characters hidden. */
19
+ export declare function promptSecret(question: string): Promise<string>;
20
+ export declare function promptText(question: string, fallback?: string): Promise<string>;
21
+ //# sourceMappingURL=prompt.d.ts.map
@@ -0,0 +1,63 @@
1
+ import { createInterface } from 'node:readline/promises';
2
+ import { stdin, stdout } from 'node:process';
3
+ /**
4
+ * Reading a passphrase.
5
+ *
6
+ * There is deliberately **no `--passphrase` flag**. A secret passed on the command line lands in
7
+ * the shell's history file and is visible to every other process on the machine through the
8
+ * process list — for a passphrase that is meant to hold for eighteen years, that is not a trade
9
+ * worth making for a few saved keystrokes.
10
+ *
11
+ * `EGEHAN_PASSPHRASE` exists for automation. It is better than a flag and still worse than
12
+ * typing: an environment variable is inherited by every child process. The CLI says so when it
13
+ * uses one.
14
+ */
15
+ export const PASSPHRASE_ENV = 'EGEHAN_PASSPHRASE';
16
+ export class PromptError extends Error {
17
+ constructor(message) {
18
+ super(message);
19
+ this.name = 'PromptError';
20
+ }
21
+ }
22
+ export function passphraseFromEnvironment() {
23
+ const value = process.env[PASSPHRASE_ENV];
24
+ return value === undefined || value === '' ? null : value;
25
+ }
26
+ /** Asks a question with the typed characters hidden. */
27
+ export async function promptSecret(question) {
28
+ if (stdin.isTTY !== true) {
29
+ throw new PromptError(`A passphrase is needed, but this is not an interactive terminal. Set ${PASSPHRASE_ENV} ` +
30
+ 'to supply one without a prompt.');
31
+ }
32
+ const rl = createInterface({ input: stdin, output: stdout, terminal: true });
33
+ // readline writes every keystroke back to the terminal; this intercepts that so the passphrase
34
+ // never appears on screen or in a scrollback buffer.
35
+ const muteable = rl;
36
+ let muted = false;
37
+ muteable._writeToOutput = (text) => {
38
+ if (!muted)
39
+ stdout.write(text);
40
+ };
41
+ try {
42
+ const answer = rl.question(question);
43
+ muted = true;
44
+ const value = await answer;
45
+ stdout.write('\n');
46
+ return value;
47
+ }
48
+ finally {
49
+ muted = false;
50
+ rl.close();
51
+ }
52
+ }
53
+ export async function promptText(question, fallback = '') {
54
+ const rl = createInterface({ input: stdin, output: stdout });
55
+ try {
56
+ const answer = (await rl.question(question)).trim();
57
+ return answer === '' ? fallback : answer;
58
+ }
59
+ finally {
60
+ rl.close();
61
+ }
62
+ }
63
+ //# sourceMappingURL=prompt.js.map
@@ -0,0 +1,51 @@
1
+ import type { EgehanRules } from '../spec/rules.js';
2
+ import type { Language, Tone } from '../engine/types.js';
3
+ /**
4
+ * `.egehanrc.json` — the per-project settings file.
5
+ *
6
+ * Validation is strict and the messages name the offending key and the accepted values. A config
7
+ * file is edited by hand, usually months after it was written, and "invalid configuration" with no
8
+ * further detail is how a tool teaches people to delete the file and start over.
9
+ *
10
+ * Note what is *not* here: nothing that would change the narration for one machine but not
11
+ * another. Language and tone are project-wide decisions recorded in the file, so two developers
12
+ * running the tool on the same repository produce the same chronicle.
13
+ */
14
+ export declare const TONES: readonly Tone[];
15
+ /**
16
+ * Output formats.
17
+ *
18
+ * `both` means the two artifacts a project keeps — the Markdown chronicle and the interactive
19
+ * HTML timeline. The JSON report is a separate opt-in because it is the machine format: it carries
20
+ * the generation timestamp and is meant for tooling, not for reading.
21
+ */
22
+ export declare const FORMATS: readonly ["md", "html", "json", "both", "all"];
23
+ export type OutputFormat = (typeof FORMATS)[number];
24
+ export declare const THEMES: readonly ["auto", "light", "dark"];
25
+ export type ChronicleTheme = (typeof THEMES)[number];
26
+ export interface EgehanConfig {
27
+ readonly projectName: string | null;
28
+ /** Opt-in, free text, never generated. Empty in this repository by design. */
29
+ readonly dedication: string | null;
30
+ readonly language: Language;
31
+ readonly tone: Tone;
32
+ readonly theme: ChronicleTheme;
33
+ readonly redactEmails: boolean;
34
+ readonly anonymizeAuthors: boolean;
35
+ readonly includeMergeCommits: boolean;
36
+ readonly format: OutputFormat;
37
+ readonly output: string;
38
+ }
39
+ export declare class ConfigError extends Error {
40
+ constructor(message: string);
41
+ }
42
+ export declare function defaultConfig(rules: EgehanRules): EgehanConfig;
43
+ export declare function configPath(root: string, rules: EgehanRules): string;
44
+ export declare function configExists(root: string, rules: EgehanRules): boolean;
45
+ /** Reads `.egehanrc.json` when present, merged over the defaults. */
46
+ export declare function loadConfig(root: string, rules: EgehanRules): EgehanConfig;
47
+ /** Applies a partial object (a config file or CLI flags) over a base config, validating as it goes. */
48
+ export declare function mergeConfig(base: EgehanConfig, patch: unknown, source: string): EgehanConfig;
49
+ /** Serializes a config for `.egehanrc.json`, with a pointer to the schema for editors. */
50
+ export declare function serializeConfig(config: EgehanConfig): string;
51
+ //# sourceMappingURL=config.d.ts.map