Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { z } from 'zod';
import { skillStateFieldRegistry } from './field-registry.ts';
export const SKILL_STATE_FILENAME = 'skill-state.yml';
export const SKILL_STATE_TARGETS = ['claude-cowork', 'cli-hosts'] as const;
export type SkillStateTarget = (typeof SKILL_STATE_TARGETS)[number];
export type SkillStateSurface =
| 'server-build-and-open'
| 'electron-build-and-open'
| 'cli-npx-skills-add'
| 'desktop-direct'
| 'cli-start';
export const SKILL_STATE_SURFACES: ReadonlyArray<SkillStateSurface> = [
'server-build-and-open',
'electron-build-and-open',
'cli-npx-skills-add',
'desktop-direct',
'cli-start',
];
export const SKILL_STATE_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
export const SKILL_STATE_SCHEMA_VERSION = 1;
const TargetEntrySchema = z.looseObject({
version: z
.string()
.regex(SKILL_STATE_VERSION_RE, 'version must match /^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.-]+)?$/')
.register(skillStateFieldRegistry, {
description: 'Recorded skill version for this target.',
}),
recordedAt: z.iso.datetime().register(skillStateFieldRegistry, {
description:
'ISO 8601 timestamp of the most recent successful write. Updated on every write, including reinstalls of the same version.',
}),
surface: z
.enum(SKILL_STATE_SURFACES as readonly [SkillStateSurface, ...SkillStateSurface[]])
.register(skillStateFieldRegistry, {
description: 'Install-source surface that recorded this entry.',
})
.optional(),
});
const BundleDecisionEntrySchema = z.looseObject({
enabled: z.boolean().register(skillStateFieldRegistry, {
description: 'Whether this user-global skill bundle is opted in.',
}),
decidedAt: z.iso.datetime().register(skillStateFieldRegistry, {
description: 'ISO 8601 timestamp of the opt-in / opt-out decision.',
}),
});
export const SkillStateSchema = z.looseObject({
schema: z.literal(SKILL_STATE_SCHEMA_VERSION).register(skillStateFieldRegistry, {
description: 'Schema major version. Bumped only on breaking shape changes.',
}),
targets: z
.looseObject({
'claude-cowork': TargetEntrySchema.optional(),
'cli-hosts': TargetEntrySchema.optional(),
})
.register(skillStateFieldRegistry, {
description: 'Per-target install-state entries. Absent target = no recorded install.',
})
.default({}),
bundles: z
.record(z.string(), BundleDecisionEntrySchema)
.register(skillStateFieldRegistry, {
description:
'Per-bundle opt-in decisions keyed by install name. Absent key = no recorded decision.',
})
.optional(),
installsReported: z
.array(z.string())
.register(skillStateFieldRegistry, {
description:
'Skill installs already reported to skills.sh from this machine, as `<owner/repo>#<skill>`. Append-only; presence suppresses a re-report.',
})
.optional(),
});
export type SkillState = z.infer<typeof SkillStateSchema>;
export type SkillStateTargetEntry = z.infer<typeof TargetEntrySchema>;
export type SkillStateBundleEntry = z.infer<typeof BundleDecisionEntrySchema>;
export function resolveBundleEnabled(
decision: boolean | null,
opts: { installedOnDisk: boolean },
): boolean {
return decision ?? opts.installedOnDisk;
}
export function emptySkillState(): SkillState {
return {
schema: SKILL_STATE_SCHEMA_VERSION,
targets: {},
};
}