Ucks
A home for all the ucks you don't give — the small commands too specific to
become a project and too useful to leave unscripted. f is where they live and
how they run; this page is the contract they satisfy.
A uck is a unit of f functionality. The builtins are ucks; extensions are
ucks; f config add ucks <source> is the same mechanism pointed at a different
source. An uck is only a word when prefixed with f-.
What ships on a fresh install is listed on the Builtins page.
A uck is a directory containing an index.js (plus any supporting files).
The index.js exports a register(ctx) function.
The contract
// index.js
export function register(ctx) {
// ctx.fVersion — f's version, e.g. "0.4.0"
// ctx.contractVersion — the contract version this core implements (2)
// ctx.self — this uck's own name
// that's all — there is no peer view at register time (see below)
return {
name: "myuck", // the word after `f`
desc: "what it does (terse)", // shown by `f search` and `f <name> --help`
run: (argv, args, runCtx) => {
// args._ is the remaining CLI args
// argv is the full argv
// runCtx has the three keys above PLUS ucks + registry — see below
process.stdout.write("hi\n");
},
};
}
export default { register };
- Return one uck object, or an array of them to register several from one module.
runreceives the parsed arguments;args._is the array of remaining (positional) CLI args.- Full Node.js runtime —
child_process,fs,http,import, the network. No sandbox.
One ctx shape, two moments
register() receives a subset of what run() receives — not an identical
object. run() gets five keys: fVersion, contractVersion, self, ucks,
registry. register() gets the first three, and no view of its peers:
- At register time:
fVersion,contractVersion,self. That is the whole object. Peer discovery is not available, by design. - At run time: plus
ucks(every registered uck, name + desc — the same dataf helpprints) andregistry(name → everything that uck returned). Inter-uck calls belong here, and can only go here.
Because the subset runs one way — register ctx ⊂ run ctx — code written against
the register-time object also typechecks inside run(). The reverse does not
hold, which is the point.
Why the keys are absent rather than empty. An earlier core handed
register() a partial registry — "whatever has loaded so far" — and the rule
was "feature detection only, never an authoritative lookup". That rule was
patching something unfixable: the partial view tracked load order and source
kind, and npm sources merge after the whole store pass, so a store uck could
never see an npm uck while an npm uck always saw the store. Renaming a bucket
flipped the answer. Object.freeze({}) is not better — it would keep the
documented "creds" in ctx.registry idiom syntactically alive while making it
always false, and a uck that trusts it degrades to a fallback reporting
"no-store" as "not configured". An absent key throws instead. Both failure modes
are now loud, at load, on the offending line.
export function register(_ctx) {
// Do not reach for peers here — ctx.registry is undefined at this point.
return {
name: "myuck",
desc: "borrow a token",
run: (_argv, _args, ctx) => {
const creds = ctx.registry.creds?.credsApi;
if (creds) creds.get("my.forge.example.com").then(process.stdout.write);
},
};
}
contractVersion is an interface number, not a release number: fVersion
("0.4.0") tells you which build of f is running, contractVersion (2) which
contract it speaks. A uck written against contract 2 can branch on it at
register time, before returning anything — it survives precisely because it is
the only pre-run signal there is. It says nothing about a peer's release
cadence — feature-detect credsApi, configApi or a credential provider on its
own surface, not on this number.
ctx.registry is the only peer accessor, and run() is the only moment
it exists. ctx.uck(name) — 0.3.0's sugar over registry[name] — is deleted,
with no deprecation cycle: the key is absent, so a uck still calling it fails
loud (ctx.uck is not a function) instead of quietly falling back to a socket
read that reports "no-store" as "not configured". The map is read-only by
convention: registration happens through register(), never by mutating it.
A uck may export anything else it wants — configApi, credsApi, skills,
your own fields. Core ignores what it does not know; other ucks read it off
ctx.registry. One export is read straight off the module, not the registry:
credentialProvider, which is how a uck becomes a credential provider — see
Credentials.
The store
Every uck f knows about lives in ~/.f/ucks/<bucket>/.
<bucket>is one source: the repo basename (git), path basename (local), or an explicitnameon the source. The path records provenance by construction.- A git bucket is the clone of its repo,
.git/and all. Uck directories are found at any depth inside the clone, so a repo can organise ucks into subdirectories. Installed ucks are checkouts:git log,git diffandgit blamework on them. - A local bucket is a copy of the path you added — a local source is
already a checkout, and the one you edit. Unlike a clone, a local bucket is
walked one level deep (
<bucket>/<name>/index.js), so keep ucks at the top of the directory you point at. - First install seeds
~/.f/f.config.jsonwith the defaults repo, then clones each configured source into the store (only if not already present). - Normal runs just load the store — instant, no network.
f upfetches and resets every bucket (see Update).- The bucket is a cache. Anything you edit under
~/.f/ucks/is discarded on the nextf up. Publish changes withf uck pushinstead.
A uck that needs a third-party library declares it in its own package.json;
f runs npm i in that uck's directory on install and on f up. Dependencies
belong to the uck, never to f core.
That package.json is also what makes an ESM uck loadable. Node decides a
.js file's module type from the nearest package.json, so an index.js
written with import/export needs "type": "module" somewhere above it:
// my-ucks/hello/package.json
{ "type": "module" }
Git sources do not need it — f writes the marker into every ESM uck in a clone
after each install and after every f up. A uck that already declares a type
is left alone; only ESM-looking ucks get one, so a genuine CommonJS uck is not
flipped by a marker it never asked for.
Local sources get no marker, so an ESM uck installed from a path fails to load
(Unexpected token 'export') until you add one. This bites on first try, and it
survives f up — a local bucket is re-copied from its source, so the missing
marker comes back with the copy.
Shadowing
If two sources provide the same uck name, the later source wins (project config is read after global, so a project uck overrides a same-named default). Both copies stay in the store; only the later one loads.
Adding a uck
As a local source — create the directory, add it to f.config.json. A
local bucket is walked one level deep, so ucks are subdirectories of the path
you point at:
my-ucks/
ls/
index.js
package.json # { "type": "module" } — see ESM note above
// my-ucks/ls/index.js
import { execSync } from "node:child_process";
export function register(_ctx) {
return {
name: "ls",
desc: "list files (terse)",
run: (_argv, args) => {
const target = (args._ ?? ["."])[0];
const out = execSync(`ls -1 ${target}`, {
encoding: "utf8",
stdio: ["pipe", "pipe", "pipe"],
});
process.stdout.write(out);
},
};
}
export default { register };
// f.config.json
{ "ucks": ["./my-ucks"] }
f copies it into ~/.f/ucks/my-ucks/ls/ and it is available as f ls. Point
ing at a single uck directory (./my-ucks/ls) also works; it just nests the
uck under a bucket named after itself.
As a repo — put uck directories in a git repo (v/index.js,
w/index.js, …) and add the repo URL to f.config.json. f clones it into
~/.f/ucks/<bucket>/ and loads every uck directory inside it, at any depth.
As a published package — add the package name to ucks and f fetches it
on the next run. There is no install command: f uck handles authoring and
pushing, not installing.
// f.config.json
{ "ucks": ["@fcli.dev/ucks"] }
f runs npm pack <spec> and unpacks the tarball into
~/.f/ucks/<bucket>/, so nothing lands in a local node_modules and the
project's own dependencies are untouched. A git ref pins the source
(@fcli.dev/ucks#0.2.0).
A published bundle holds one directory per uck under dist/, plus a shared
lib/ and a version-stamped manifest.json; on install dist/ is rebased onto
the bucket root. Single-uck packages are the same idea with one directory and a
root package.json — f reads the version from either.
Publishing is an ordinary package that exports register(ctx) and carries the
fcli-uck keyword; that keyword is what lists it on
Ucks. See Extend for the packaging walk-through and
Config for every source form.
@fcli.dev/ucks is the default
bundle: f seeds it into f.config.json and installs it on first run.