create-ken 0.0.0-stage → 0.1.1
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.
- package/LICENSE +21 -0
- package/README.md +15 -2
- package/dist/cli.js +140 -0
- package/package.json +27 -3
- package/template/.agents/hooks.json +14 -0
- package/template/.claude/settings.json +14 -0
- package/template/.envrc +18 -0
- package/template/.gitattributes +1 -0
- package/template/.pi/extensions/ken-hooks.ts +52 -0
- package/template/AGENTS.md +23 -0
- package/template/README.md +5 -0
- package/template/gitignore +4 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Xiaoxing Hu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
-
#
|
|
1
|
+
# create-ken
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Make a folder a ken root for an agent harness: `ken init`, then the template's files,
|
|
4
|
+
`AGENTS.md`, `README.md`, the session-start hook of Claude Code, Codex and pi, and the env
|
|
5
|
+
files, adding only what is missing. A rerun in a root adds the files a newer template has and
|
|
6
|
+
names each file that differs from it, with the `diff` to run.
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
npm create ken ~/ken
|
|
10
|
+
cd ~/ken && npm create ken # a rerun
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
From a clone, with no build: `node packages/create-ken/src/cli.ts <dir>`. The template is
|
|
14
|
+
`template/`, plain files, `gitignore` written as `.gitignore`, since npm leaves a file of that
|
|
15
|
+
name out of a package; `CLAUDE.md` and `.codex/hooks.json` are links, made at run time. What
|
|
16
|
+
each file is for: `docs/templates.md` at the repo root.
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// create-ken [<dir>]: a ken root for an agent harness (docs/templates.md). `ken init`, then the
|
|
3
|
+
// template's files, adding only what is missing, so a rerun is a root's update path.
|
|
4
|
+
import { spawnSync } from 'node:child_process';
|
|
5
|
+
import { appendFileSync, constants, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, symlinkSync } from 'node:fs';
|
|
6
|
+
import { dirname, join, resolve } from 'node:path';
|
|
7
|
+
import { fileURLToPath } from 'node:url';
|
|
8
|
+
const TEMPLATE = fileURLToPath(new URL('../template', import.meta.url));
|
|
9
|
+
// ken's bin as its manifest names it: src/cli.ts in a clone, dist/cli.js in a package
|
|
10
|
+
const MANIFEST = fileURLToPath(import.meta.resolve('@unclex/ken/package.json'));
|
|
11
|
+
const KEN = resolve(dirname(MANIFEST), JSON.parse(readFileSync(MANIFEST, 'utf8')).bin.ken);
|
|
12
|
+
const INSTALL = 'npm install -g @unclex/ken';
|
|
13
|
+
// npm leaves a file named .gitignore out of a package, so the template keeps it as gitignore
|
|
14
|
+
const IGNORE = 'gitignore';
|
|
15
|
+
// an npm package carries no link: these are made here, name to target
|
|
16
|
+
const LINKS = { 'CLAUDE.md': 'AGENTS.md', '.codex/hooks.json': '../.agents/hooks.json' };
|
|
17
|
+
/** `s` as one shell word, so a command in a message can be pasted. */
|
|
18
|
+
const q = (s) => /^[A-Za-z0-9_./@%+=:,-]+$/.test(s) ? s : `'${s.replaceAll("'", "'\\''")}'`;
|
|
19
|
+
const stop = (message) => {
|
|
20
|
+
process.stderr.write(`create-ken: ${message}\n`);
|
|
21
|
+
process.exit(1);
|
|
22
|
+
};
|
|
23
|
+
const lstat = (path) => lstatSync(path, { throwIfNoEntry: false });
|
|
24
|
+
const lines = (text) => text.split('\n').filter((line) => line.trim());
|
|
25
|
+
const args = process.argv.slice(2);
|
|
26
|
+
if (args.some((a) => a === '-h' || a === '--help')) {
|
|
27
|
+
process.stdout.write(`Usage: create-ken [<dir>], run as \`npm create ken <dir>\`: make <dir>, default the current
|
|
28
|
+
folder, a ken root for an agent harness. Runs \`ken init <dir>\`, then copies the template,
|
|
29
|
+
AGENTS.md, README.md, the session-start hooks and the env files, never overwriting. A rerun
|
|
30
|
+
adds the files a newer template has and names each file that differs from it.
|
|
31
|
+
npm create ken ~/ken
|
|
32
|
+
cd ~/ken && npm create ken # a rerun: only what is missing
|
|
33
|
+
`);
|
|
34
|
+
process.exit(0);
|
|
35
|
+
}
|
|
36
|
+
if (args.length > 1)
|
|
37
|
+
stop(`takes one folder, got ${args.length} arguments. Quote a path with spaces, e.g. \`npm create ken ~/ken\`.`);
|
|
38
|
+
if (args[0]?.startsWith('-'))
|
|
39
|
+
stop(`does not take ${q(args[0])}: it takes one folder, default the current one. Run \`create-ken --help\`.`);
|
|
40
|
+
try {
|
|
41
|
+
// ken init first: a folder it refuses, such as one inside another root, gets no file
|
|
42
|
+
const init = spawnSync(process.execPath, [KEN, 'init', resolve(args[0] ?? '.')], {
|
|
43
|
+
encoding: 'utf8'
|
|
44
|
+
});
|
|
45
|
+
process.stdout.write(init.stdout);
|
|
46
|
+
process.stderr.write(init.stderr);
|
|
47
|
+
if (init.status !== 0)
|
|
48
|
+
process.exit(init.status ?? 1);
|
|
49
|
+
const root = realpathSync.native(resolve(args[0] ?? '.'));
|
|
50
|
+
const made = [];
|
|
51
|
+
const same = [];
|
|
52
|
+
const differs = [];
|
|
53
|
+
for (const rel of readdirSync(TEMPLATE, { recursive: true }).sort()) {
|
|
54
|
+
const from = join(TEMPLATE, rel);
|
|
55
|
+
if (!lstatSync(from).isFile())
|
|
56
|
+
continue;
|
|
57
|
+
if (rel === IGNORE) {
|
|
58
|
+
// ken init owns .gitignore too: the template's lines it lacks are added, as init adds its own
|
|
59
|
+
const path = join(root, '.gitignore');
|
|
60
|
+
const text = readFileSync(path, 'utf8');
|
|
61
|
+
const have = new Set(lines(text).map((line) => line.trimEnd()));
|
|
62
|
+
const lacking = lines(readFileSync(from, 'utf8')).filter((line) => !have.has(line));
|
|
63
|
+
if (!lacking.length)
|
|
64
|
+
same.push('.gitignore');
|
|
65
|
+
else {
|
|
66
|
+
appendFileSync(path, `${text && !text.endsWith('\n') ? '\n' : ''}${lacking.join('\n')}\n`);
|
|
67
|
+
made.push(`.gitignore, added ${lacking.join(' ')}`);
|
|
68
|
+
}
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
const to = join(root, rel);
|
|
72
|
+
const there = lstat(to);
|
|
73
|
+
if (!there) {
|
|
74
|
+
mkdirSync(dirname(to), { recursive: true });
|
|
75
|
+
copyFileSync(from, to, constants.COPYFILE_EXCL);
|
|
76
|
+
made.push(rel);
|
|
77
|
+
}
|
|
78
|
+
else if (there.isFile() && readFileSync(to).equals(readFileSync(from)))
|
|
79
|
+
same.push(rel);
|
|
80
|
+
else
|
|
81
|
+
differs.push(`${rel}: \`diff ${q(from)} ${q(to)}\``);
|
|
82
|
+
}
|
|
83
|
+
for (const [name, target] of Object.entries(LINKS)) {
|
|
84
|
+
const path = join(root, name);
|
|
85
|
+
const there = lstat(path);
|
|
86
|
+
if (!there) {
|
|
87
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
88
|
+
symlinkSync(target, path);
|
|
89
|
+
made.push(`${name} -> ${target}`);
|
|
90
|
+
}
|
|
91
|
+
else if (there.isSymbolicLink() && readlinkSync(path) === target)
|
|
92
|
+
same.push(name);
|
|
93
|
+
else
|
|
94
|
+
differs.push(`${name}: not the link ${name} -> ${target}, which the template has`);
|
|
95
|
+
}
|
|
96
|
+
const ken = join(root, '.ken');
|
|
97
|
+
const settings = readFileSync(ken, 'utf8');
|
|
98
|
+
if (/^template\.name=/m.test(settings))
|
|
99
|
+
same.push('.ken');
|
|
100
|
+
else {
|
|
101
|
+
appendFileSync(ken, `${settings.endsWith('\n') ? '' : '\n'}template.name=agents\n`);
|
|
102
|
+
made.push('.ken, added template.name=agents');
|
|
103
|
+
}
|
|
104
|
+
const list = (items) => items.map((item) => ` ${item}\n`).join('');
|
|
105
|
+
let out = made.length
|
|
106
|
+
? `From the template, made or added to in ${root}:\n${list(made)}`
|
|
107
|
+
: `${root} has every file of the template: nothing was made.\n`;
|
|
108
|
+
if (same.length)
|
|
109
|
+
out += `Left alone, already as the template has them: ${same.join(' ')}\n`;
|
|
110
|
+
if (differs.length)
|
|
111
|
+
out +=
|
|
112
|
+
"Left alone, different from the template: yours to keep, or to compare with the template's and bring over what it adds:\n" +
|
|
113
|
+
list(differs);
|
|
114
|
+
const ok = (cmd, ...cmdArgs) => spawnSync(cmd, cmdArgs).status === 0;
|
|
115
|
+
const next = [];
|
|
116
|
+
// npm create puts its temporary install's node_modules/.bin on PATH, and the ken there, this
|
|
117
|
+
// package's dependency, is gone after the run: only a ken outside one is installed
|
|
118
|
+
const path = (process.env.PATH ?? '')
|
|
119
|
+
.split(':')
|
|
120
|
+
.filter((dir) => !dir.includes('/node_modules/.bin'))
|
|
121
|
+
.join(':');
|
|
122
|
+
if (spawnSync('sh', ['-c', 'command -v ken'], { env: { ...process.env, PATH: path } }).status)
|
|
123
|
+
next.push(`${INSTALL} # ken is not on PATH, and the hooks and AGENTS.md call it`);
|
|
124
|
+
const git = ok('git', '-C', root, 'rev-parse', '--is-inside-work-tree');
|
|
125
|
+
if (!git)
|
|
126
|
+
next.push(`git -C ${q(root)} init`);
|
|
127
|
+
if (!git || made.length)
|
|
128
|
+
next.push(`git -C ${q(root)} add . && git -C ${q(root)} commit -m 'A ken root'`);
|
|
129
|
+
if (made.length)
|
|
130
|
+
next.push(`start an agent session in ${q(root)}: its hook runs \`ken status\`. Codex and pi ask to trust the folder first, and Codex again for the hooks.`);
|
|
131
|
+
if (next.length)
|
|
132
|
+
out += `Next:\n${list(next)}`;
|
|
133
|
+
process.stdout.write(out);
|
|
134
|
+
}
|
|
135
|
+
catch (e) {
|
|
136
|
+
const { code, path, syscall } = e;
|
|
137
|
+
if (!code || !path)
|
|
138
|
+
throw e;
|
|
139
|
+
stop(`could not ${syscall ?? 'reach'} ${path}: ${code}. Fix that, e.g. move aside what is in the way, then run create-ken again: it adds only what is missing.`);
|
|
140
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-ken",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Make a folder a ken root for an agent harness, or add what a newer template has: `npm create ken <dir>`.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/xiaoxinghu/ken.git",
|
|
10
|
+
"directory": "packages/create-ken"
|
|
11
|
+
},
|
|
12
|
+
"homepage": "https://unclex.net",
|
|
13
|
+
"bin": {
|
|
14
|
+
"create-ken": "./dist/cli.js"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"template"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=24"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public"
|
|
25
|
+
},
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"@unclex/ken": "0.1.1"
|
|
28
|
+
},
|
|
29
|
+
"scripts": {}
|
|
6
30
|
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"SessionStart": [
|
|
4
|
+
{
|
|
5
|
+
"hooks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "command",
|
|
8
|
+
"command": "if command -v ken >/dev/null 2>&1; then ken status; else echo 'This is a ken root, and ken is not installed: run npm install -g @unclex/ken, then start a new session.'; fi"
|
|
9
|
+
}
|
|
10
|
+
]
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"SessionStart": [
|
|
4
|
+
{
|
|
5
|
+
"hooks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "command",
|
|
8
|
+
"command": "if command -v ken >/dev/null 2>&1; then ken status; else echo 'This is a ken root, and ken is not installed: run npm install -g @unclex/ken, then start a new session.'; fi"
|
|
9
|
+
}
|
|
10
|
+
]
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
}
|
package/template/.envrc
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# The top of the direnv chain: direnv loads the nearest .envrc above the current folder, so a
|
|
2
|
+
# checkout in .repos/ with none of its own gets this one, and one with its own reaches it with
|
|
3
|
+
# source_up_if_exists.
|
|
4
|
+
|
|
5
|
+
# Secrets for the whole root, kept out of git by .gitignore.
|
|
6
|
+
dotenv_if_exists
|
|
7
|
+
|
|
8
|
+
# A Unix socket path is capped at 104 bytes on macOS and worktree paths run near 90,
|
|
9
|
+
# so each tool that makes a socket in its working folder is pointed under $TMPDIR instead.
|
|
10
|
+
tmp=${TMPDIR:-/tmp}
|
|
11
|
+
tmp=${tmp%/}
|
|
12
|
+
# overmind: one socket per folder whose .envrc loads this, named by a checksum of its path;
|
|
13
|
+
# a repo that runs overmind in two worktrees at once puts this line in its own .envrc.
|
|
14
|
+
export OVERMIND_SOCKET="$tmp/overmind-$(printf %s "$PWD" | cksum | cut -d' ' -f1).sock"
|
|
15
|
+
# postgres: a server started here puts its socket in $PGHOST, and psql looks for it there.
|
|
16
|
+
export PGHOST="$tmp"
|
|
17
|
+
# ssh: a ControlMaster socket for git, named by %C, a hash of the connection, so it stays short.
|
|
18
|
+
export GIT_SSH_COMMAND="ssh -o ControlPath=$tmp/ssh-%C"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
log.md merge=union
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
// pi reads no hook file, so this runs the SessionStart hooks of .agents/hooks.json, written in
|
|
2
|
+
// Claude Code's schema, on pi's session_start, with the stdin JSON Claude Code and Codex send.
|
|
3
|
+
import { spawnSync } from 'node:child_process'
|
|
4
|
+
import { readFileSync } from 'node:fs'
|
|
5
|
+
import { fileURLToPath } from 'node:url'
|
|
6
|
+
|
|
7
|
+
type Group = { matcher?: string; hooks: { type: string; command: string; timeout?: number }[] }
|
|
8
|
+
type Ctx = { cwd: string }
|
|
9
|
+
type Pi = { on(event: string, handler: (event: never, ctx: Ctx) => unknown): void }
|
|
10
|
+
|
|
11
|
+
const HOOKS = fileURLToPath(new URL('../../.agents/hooks.json', import.meta.url))
|
|
12
|
+
// pi's session_start reasons as Claude Code's SessionStart sources
|
|
13
|
+
const SOURCES: Record<string, string> = { new: 'clear', reload: 'startup' }
|
|
14
|
+
|
|
15
|
+
/** The stdout of the SessionStart hooks whose matcher matches `source`. */
|
|
16
|
+
function sessionStart(source: string, cwd: string) {
|
|
17
|
+
let groups: Group[] = []
|
|
18
|
+
try {
|
|
19
|
+
groups = JSON.parse(readFileSync(HOOKS, 'utf8')).hooks?.SessionStart ?? []
|
|
20
|
+
} catch {
|
|
21
|
+
return ''
|
|
22
|
+
}
|
|
23
|
+
const stdin = JSON.stringify({ hook_event_name: 'SessionStart', cwd, source })
|
|
24
|
+
return groups
|
|
25
|
+
.filter((g) => !g.matcher || g.matcher === '*' || new RegExp(`^(?:${g.matcher})$`).test(source))
|
|
26
|
+
.flatMap((g) => g.hooks.filter((h) => h.type === 'command'))
|
|
27
|
+
.map(
|
|
28
|
+
(h) =>
|
|
29
|
+
spawnSync('sh', ['-c', h.command], {
|
|
30
|
+
cwd,
|
|
31
|
+
input: stdin,
|
|
32
|
+
encoding: 'utf8',
|
|
33
|
+
timeout: (h.timeout ?? 600) * 1000
|
|
34
|
+
}).stdout ?? ''
|
|
35
|
+
)
|
|
36
|
+
.join('')
|
|
37
|
+
.trim()
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export default function (pi: Pi) {
|
|
41
|
+
let context = ''
|
|
42
|
+
pi.on('session_start', (event: { reason: string }, ctx) => {
|
|
43
|
+
context = sessionStart(SOURCES[event.reason] ?? event.reason, ctx.cwd)
|
|
44
|
+
})
|
|
45
|
+
// session_start has no way to reach the model: its output goes with the first prompt
|
|
46
|
+
pi.on('before_agent_start', () => {
|
|
47
|
+
if (!context) return
|
|
48
|
+
const content = context
|
|
49
|
+
context = ''
|
|
50
|
+
return { message: { customType: 'ken-hooks', content, display: false } }
|
|
51
|
+
})
|
|
52
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# A ken root
|
|
2
|
+
|
|
3
|
+
This is a ken root, a knowledge base. Its CLI is `ken`: `ken help` lists the commands, with
|
|
4
|
+
examples, and when `ken` is not a command, `npm install -g @unclex/ken` installs it.
|
|
5
|
+
`ken status` is the overview the session-start hook printed. README.md, the front page, says
|
|
6
|
+
what the root is for.
|
|
7
|
+
|
|
8
|
+
- A section is a top-level folder with a README.md listing its pages, Markdown files, one line
|
|
9
|
+
each; a new section's line goes under `## Sections` in README.md. No page sits at the top.
|
|
10
|
+
- Name code the way `ken path` reads it, `<key>:<path>#<symbol>`, never by line number or
|
|
11
|
+
absolute path.
|
|
12
|
+
- Run `ken lint` after changing pages, then commit when the root is in git.
|
|
13
|
+
- After an ingest, an answered question, a page or a task, run `ken log <kind> <subject> <what>`
|
|
14
|
+
before the commit. `ken status` shows the recent lines; grep `log.md` for older ones, never
|
|
15
|
+
read it whole.
|
|
16
|
+
- A log line ending in `s=<id>` names its session's digest: when the line is not enough,
|
|
17
|
+
`ken session <id>` prints its last entries and `ken session <id> <range>` others;
|
|
18
|
+
`grep -il <pattern> .sessions/*.jsonl` finds the sessions that mention something.
|
|
19
|
+
- A checkout in `.repos/` needs `CLAUDE.md -> AGENTS.md`, which `ken get` makes in a fresh one:
|
|
20
|
+
this root's `CLAUDE.md` hides a checkout's AGENTS.md from Claude Code.
|
|
21
|
+
- A skill goes in `.agents/skills/<name>/SKILL.md`; with the first one, make the link
|
|
22
|
+
`.claude/skills -> ../.agents/skills` for Claude Code.
|
|
23
|
+
- Auto-memory is shared by every session at this root: knowledge goes in a page.
|