fcli

Extend

For ucks you want to version, publish, or depend on, wrap them in an npm package. Extensions are packages that export a register(ctx) function — the same contract as ucks.

Full Node.js runtime — no sandboxing. Extensions can import each other, call child_process, hit the network, modify core behavior, whatever.

1. Create an extension

my-f-ext/
  package.json
  index.js

package.json:

{
  "name": "@myorg/f-my-ext",
  "version": "0.1.0",
  "type": "module",
  "main": "./index.js"
}

index.js:

export function register(ctx) {
  // ctx.fVersion        — f's version
  // ctx.contractVersion — the contract this core speaks (2)
  // ctx.self            — this package's name
  // (no ucks/registry here — peer access is run-time only)

  return {
    name: "myuck",
    desc: "what it does (terse)",
    run: (argv, args, runCtx) => {
      // runCtx.ucks     — [{name, desc}] of every loaded uck
      // runCtx.registry — name -> everything that uck returned
      console.log("hello", args._.join(" "));
    },
  };
  // Can also return an array: [ {name: "a", ...}, {name: "b", ...} ]
}
export default { register };

2. Register it in f.config.json

Add it to the ucks array — an npm package is a source like any other:

{
  "ucks": [
    "@myorg/f-my-ext",
    "./local-path/to/ext",
    { "source": "github:user/repo", "ref": "main" }
  ]
}

Source formats:

  • npm — "@scope/name" — fetched with npm pack into a bucket under ~/.f/ucks/ on f up, and loaded from there. It does not need to be in your project's node_modules. (A legacy path still resolves an npm source through node_modules if one happens to be installed there; see Precedence.)
  • local — "./my-ext" or "/abs/path" — a dir with package.json or index.js.
  • git — "github:user/repo" or "git+https://…".
  • object — { "source": "…", "ref": "branch", "name": "bucket" }.

3. Install and run

Add the package to ucks and run f up. f fetches the tarball into ~/.f/ucks/ — see Adding a uck.

// f.config.json
{ "ucks": ["@myorg/f-my-ext"] }
f up
f myuck hello

The package is a copy under the store, not a dependency of your project: nothing is added to your package.json or node_modules, and f up is what refreshes it. f uck itself has no install subcommand.

A legacy extensions key in f.config.json is still read as a source list when ucks is absent. Prefer ucks.

Extension interop

Extensions run in the full Node.js runtime, and they share the uck registry:

  • Import each other: import { helper } from "@other/f-ext"
  • Use child_process, fs, http, net — everything.
  • Call other ucks through ctx.registry in run (e.g. ctx.registry.creds), and only there — the register-time ctx does not carry registry at all, so a peer lookup before run fails loud rather than seeing a partial view.
  • Modify or override core f behavior.

No sandbox. No restrictions. Ucks are first-class.

Precedence

Later sources win, and load order is: store buckets first, then any npm source that also resolves through node_modules. Since npm sources are installed as store buckets, an npm package normally shadows a same-named uck from an earlier bucket — the shadowing is bucket order, not npm-versus-store. The node_modules step only fires for installs that predate store installs of npm sources, and it is silent when the specifier does not resolve there. Within each group, project config loads after global. See Ucks for shadowing.

Documentation for f. This page is built by the site generator.

site source