Append Wiki Log Entry

Instructions

{
  "op": "decision",
  "title": "Adopt gRPC for internal RPC",
  "body": "Streaming + typed schemas outweigh the browser-edge tax.",
  "refs": [
    "wiki/Sources/adr-004.md",
    "wiki/Concepts/grpc.md"
  ]
}

{
  "op": "note",
  "title": "Reviewed orphan pages from last sprint"
}

Implementation Reference

• src/domain/wiki/log.ts:25-52 (handler)

  Core handler function that appends a log entry to the wiki log file. It resolves wiki paths, auto-runs wiki.init if log.md doesn't exist, formats the entry using formatLogEntry, reads the existing log, and appends the new entry. Returns a mutation result with changed flag, target path, summary, date, op, and entryTitle.

  export async function appendLogEntry(context: DomainContext, args: WikiLogAppendArgs) {
    const paths = resolveWikiPaths(context, args);
    if (!(await fileExists(paths.logAbsolute))) {
      await initWiki(context, { wikiRoot: args.wikiRoot, vaultPath: args.vaultPath });
    }
  
    const date = args.date ?? todayIso();
    const block = formatLogEntry({
      date,
      op: args.op,
      title: args.title,
      body: args.body,
      refs: args.refs,
    });
  
    const previous = await readUtf8(paths.logAbsolute);
    const separator = previous.endsWith("\n\n") ? "" : previous.endsWith("\n") ? "\n" : "\n\n";
    await writeUtf8(paths.logAbsolute, `${previous}${separator}${block}`);
  
    return {
      changed: true,
      target: paths.logRelative,
      summary: `Appended ${args.op} entry to ${paths.logRelative}`,
      date,
      op: args.op,
      entryTitle: args.title,
    };
  }

• src/domain/wiki/log.ts:7-22 (helper)

  Helper function that formats a single log entry as markdown: '## [YYYY-MM-DD] <op> | <title>', followed by optional body and refs wikilink list.

  export function formatLogEntry(args: {
    date: string;
    op: string;
    title: string;
    body?: string;
    refs?: string[];
  }): string {
    const header = `## [${args.date}] ${args.op} | ${args.title}`;
    const lines: string[] = [header];
    if (args.body && args.body.trim().length > 0) {
      lines.push("", args.body.trim());
    }
    if (args.refs && args.refs.length > 0) {
      lines.push("", ...args.refs.map((ref) => `- [[${ref}]]`));
    }
    return `${lines.join("\n")}\n`;

• src/schema/wiki.ts:153-176 (schema)

  Zod schema for wiki.logAppend input args: op (enum: ingest|query|lint|note|decision|merge), title (required), body (optional), refs (optional string array), date (optional YYYY-MM-DD), wikiRoot (optional), vaultPath (optional).

  export const wikiLogAppendArgsSchema = z.object({
    op: logOpSchema.describe(
      "Log entry kind: ingest | query | lint | note | decision | merge. Becomes the `<op>` token in `## [YYYY-MM-DD] <op> | <title>`.",
    ),
    title: z
      .string()
      .min(1)
      .describe("One-line title for the entry. Becomes the `<title>` token in the heading."),
    body: z
      .string()
      .optional()
      .describe("Optional markdown body written under the heading. Omit for a heading-only entry."),
    refs: z
      .array(z.string().min(1))
      .default([])
      .describe(
        "Optional list of vault-relative paths or wiki-link targets rendered as a `Refs:` list under the entry.",
      ),
    date: dateStringSchema
      .optional()
      .describe("YYYY-MM-DD override for the entry date. Defaults to today."),
    wikiRoot: wikiRootOverrideSchema.describe("Per-call wiki directory override."),
    vaultPath: z.string().optional().describe("Per-call vault override."),
  });

• src/server/tools/wiki.ts:82-106 (registration)

  Tool registration for wiki.logAppend. Defines name 'wiki.logAppend', title 'Append Wiki Log Entry', description, inputSchema referencing wikiLogAppendArgsSchema, outputSchema (mutationResultSchema), input examples, and a handler that delegates to appendLogEntry.

  {
    name: "wiki.logAppend",
    title: "Append Wiki Log Entry",
    description:
      "Append one typed entry to `wiki/log.md` in the canonical format `## [YYYY-MM-DD] <op> | <title>`, optionally followed by a body and a `Refs:` list. The format is chosen so `grep '^## \\[' log.md | tail -20` is a valid 'recent activity' query. Use this when the agent makes a wiki-meaningful action that no other `wiki.*` tool already logs (e.g. a `decision` or `note`); `ingest` and `merge` log themselves. Auto-runs `wiki.init` if the wiki has not been scaffolded yet. Idempotent only in the trivial sense — every call appends a new entry.",
    inputSchema: wikiLogAppendArgsSchema,
    outputSchema: mutationResultSchema,
    inputExamples: [
      {
        description: "Log an architectural decision with two refs.",
        input: {
          op: "decision",
          title: "Adopt gRPC for internal RPC",
          body: "Streaming + typed schemas outweigh the browser-edge tax.",
          refs: ["wiki/Sources/adr-004.md", "wiki/Concepts/grpc.md"],
        },
      },
      {
        description: "Quick freeform note dated today.",
        input: { op: "note", title: "Reviewed orphan pages from last sprint" },
      },
    ],
    handler: (context, args) =>
      appendLogEntry(context, args as Parameters<typeof appendLogEntry>[1]),
  },

• src/domain/wiki/index.ts:7-7 (registration)

  Re-exports appendLogEntry from ./log.js so it can be imported from the domain/wiki barrel.

  export { appendLogEntry } from "./log.js";