@dayofweek/dcli 1.11.0 → 1.12.0

package/README.md

@@ -153,6 +153,35 @@ dcli data get <dataset> --limit 100 --json
 Responses are `{ dataset, total, truncated, rows }`. The CLI has no built-in
 dataset names; new datasets appear in the listing without a CLI update.
 
+## Time tracking (staff)
+
+Hours registered against time projects. The server owns every rule — project
+and participation periods, hour frames, self-financing, the reportable basis,
+who may approve — and the CLI only carries JSON.
+
+```bash
+dcli time projects list --json
+dcli time projects show <projectId> --json
+dcli time projects upsert --file project.json          # create, or update with projectId
+
+dcli time entries list --project <id> --from 2026-06-01 --to 2026-09-30 --json
+dcli time entries import --project <id> --file entries.json --dry-run
+dcli time entries import --project <id> --file entries.json --approved
+
+dcli time months list --json
+dcli time months submit --project <id> --month 2026-08
+dcli time months approve --project <id> --month 2026-08 --user-email someone@example.com
+dcli time months return --project <id> --month 2026-08 --user-email ... --comment "..."
+```
+
+`entries import` is idempotent: each entry carries an import key (explicit, or
+derived from person + date + activity + description), so re-running a file
+updates rather than duplicates. Approved rows are locked and reported as
+`skip_locked`; any invalid entry aborts the whole batch with nothing written.
+Because real rows are written, the command refuses to run without `--dry-run`
+first and `--approved` afterwards. Payload shapes are documented in the
+`time-tracking` reference that `dcli skill install` fetches for staff.
+
 ## Feedback backlog
 
 The customer feedback backlog that humans and coding agents work together.

package/dist/bin/dcli.js

@@ -1351,6 +1351,127 @@ feedback
         rejectedReason: opts.rejectedReason,
     }));
 });
+// ── Time tracking ────────────────────────────────────────────────────────────
+//
+// Hours per project. The server owns the rules (project and participation
+// periods, hour frames, self-financing, the reportable basis, approvals);
+// this group parses flags, reads JSON files and prints the response. The
+// only local rule is the irreversibility gate on import: real rows are
+// written, so --dry-run first, then --approved.
+const time = program.command("time").description("Hours per project: projects, entries, monthly sheets");
+const timeProjects = time.command("projects").description("Time projects: setup and overview");
+timeProjects
+    .command("list")
+    .description("List time projects with totals and frame usage")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (opts) => {
+    output(await getClient().listTimeProjects(opts.org));
+});
+timeProjects
+    .command("show <projectId>")
+    .description("One project: setup, person×activity×month matrix, entries with computed split, monthly sheets")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (projectId, opts) => {
+    output(await getClient().getTimeProject(projectId, opts.org));
+});
+timeProjects
+    .command("upsert")
+    .description("Create or update a time project from a JSON file (include projectId to update)")
+    .requiredOption("--file <path>", "JSON payload with the project setup (- for stdin)")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (opts) => {
+    const raw = opts.file === "-" ? readFileSync(0, "utf8") : readFileSync(opts.file, "utf8");
+    const payload = JSON.parse(raw);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("Payload must be a JSON object with the project setup");
+    }
+    output(await getClient().upsertTimeProject(payload, opts.org));
+});
+const timeEntries = time.command("entries").description("Registered hours");
+timeEntries
+    .command("list")
+    .description("Flat rows with the computed split (counted, self-financed, reportable, reasons)")
+    .option("--project <projectId>", "Only this project")
+    .option("--user <userId>", "Only this person (owners and admins)")
+    .option("--from <YYYY-MM-DD>", "First work date")
+    .option("--to <YYYY-MM-DD>", "Last work date")
+    .option("--status <status>", "draft | submitted | approved")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (opts) => {
+    output(await getClient().listTimeEntries({
+        project: opts.project,
+        user: opts.user,
+        from: opts.from,
+        to: opts.to,
+        status: opts.status,
+        org: opts.org,
+    }));
+});
+timeEntries
+    .command("import")
+    .description("Idempotent batch import of hours into one project. Requires --dry-run or --approved")
+    .requiredOption("--project <projectId>", "Target time project")
+    .requiredOption("--file <path>", "JSON: { entries: [...] } or a bare array (- for stdin)")
+    .option("--dry-run", "Validate and report what would happen, write nothing")
+    .option("--approved", "The operator approved the dry-run result")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (opts) => {
+    if (!opts.dryRun && !opts.approved) {
+        throw new Error("Refusing to write: run with --dry-run first, show the operator the summary, " +
+            "then repeat with --approved. This writes real hours, not proposals.");
+    }
+    const raw = opts.file === "-" ? readFileSync(0, "utf8") : readFileSync(opts.file, "utf8");
+    const payload = JSON.parse(raw);
+    const entries = Array.isArray(payload) ? payload : payload?.entries;
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new Error("Payload needs { entries: [...] } with at least one entry");
+    }
+    output(await getClient().importTimeEntries({
+        projectId: opts.project,
+        entries,
+        dryRun: Boolean(opts.dryRun),
+        org: opts.org,
+    }));
+});
+const timeMonths = time.command("months").description("Monthly sheets: submit, approve, return, reopen");
+timeMonths
+    .command("list")
+    .description("Months waiting for your approval (project owner), or every submitted month (admin)")
+    .option("--org <org>", "Organization slug or id (admin only)")
+    .action(async (opts) => {
+    output(await getClient().listPendingTimeMonths(opts.org));
+});
+for (const action of ["submit", "approve", "return", "reopen"]) {
+    const descriptions = {
+        submit: "Submit a month for approval (your own; admins may pass --user-email)",
+        approve: "Approve a submitted month — locks its rows (project owner or admin)",
+        return: "Return a submitted month as drafts, --comment required (project owner or admin)",
+        reopen: "Reopen an approved month for correction; it needs a new approval",
+    };
+    timeMonths
+        .command(action)
+        .description(descriptions[action])
+        .requiredOption("--project <projectId>", "Time project")
+        .requiredOption("--month <YYYY-MM>", "Month")
+        .option("--user-email <email>", "Whose month (defaults to yourself)")
+        .option("--user <userId>", "Whose month, by user id")
+        .option("--comment <text>", "Comment (required for return)")
+        .option("--org <org>", "Organization slug or id (admin only)")
+        .action(async (opts) => {
+        if (action === "return" && !opts.comment) {
+            throw new Error("--comment is required when returning a month");
+        }
+        output(await getClient().actOnTimeMonth({
+            projectId: opts.project,
+            month: opts.month,
+            action,
+            userId: opts.user,
+            userEmail: opts.userEmail,
+            comment: opts.comment,
+            org: opts.org,
+        }));
+    });
+}
 // ── Admin Commands ───────────────────────────────────────────────────────────
 //
 // These are admin-only. They're registered as hidden subcommands when the

package/dist/bundle/dcli.cjs

@@ -4773,6 +4773,52 @@ var DayOfWeekClient = class {
   async archiveSharedSkill(skillId) {
     return this.delete(`/brain/skills/${encodeURIComponent(skillId)}`);
   }
+  // ── Time tracking ─────────────────────────────────────────────────────────
+  //
+  // Hours registered against time projects. Every rule (periods, frames,
+  // self-financing, the reportable basis, who may approve) is evaluated by
+  // the server; the client only carries JSON and prints what comes back.
+  async listTimeProjects(org) {
+    const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+    return this.get(`/time/projects${qs}`);
+  }
+  async getTimeProject(projectId, org) {
+    const params = new URLSearchParams({ id: projectId });
+    if (org) params.set("org", org);
+    return this.get(`/time/projects?${params.toString()}`);
+  }
+  async upsertTimeProject(payload, org) {
+    const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+    return this.post(`/time/projects${qs}`, payload);
+  }
+  async listTimeEntries(opts) {
+    const params = new URLSearchParams();
+    if (opts?.project) params.set("project", opts.project);
+    if (opts?.user) params.set("user", opts.user);
+    if (opts?.from) params.set("from", opts.from);
+    if (opts?.to) params.set("to", opts.to);
+    if (opts?.status) params.set("status", opts.status);
+    if (opts?.org) params.set("org", opts.org);
+    const qs = params.toString();
+    return this.get(`/time/entries${qs ? `?${qs}` : ""}`);
+  }
+  async importTimeEntries(input) {
+    const qs = input.org ? `?org=${encodeURIComponent(input.org)}` : "";
+    return this.post(`/time/entries${qs}`, {
+      projectId: input.projectId,
+      dryRun: input.dryRun,
+      entries: input.entries
+    });
+  }
+  async listPendingTimeMonths(org) {
+    const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+    return this.get(`/time/months${qs}`);
+  }
+  async actOnTimeMonth(input) {
+    const { org, ...body } = input;
+    const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+    return this.post(`/time/months${qs}`, body);
+  }
   // ── Schema ────────────────────────────────────────────────────────────────
   async getSchema() {
     return this.get("/schema");
@@ -5221,7 +5267,7 @@ var import_promises4 = require("node:readline/promises");
 // package.json
 var package_default = {
   name: "@dayofweek/dcli",
-  version: "1.11.0",
+  version: "1.12.0",
   description: "CLI for the Day of Week AgTech platform \u2014 read data and submit proposals for review",
   license: "MIT",
   type: "module",
@@ -6219,6 +6265,84 @@ feedback.command("status <itemId>").description("Set status and/or priority on a
     rejectedReason: opts.rejectedReason
   }));
 });
+var time = program2.command("time").description("Hours per project: projects, entries, monthly sheets");
+var timeProjects = time.command("projects").description("Time projects: setup and overview");
+timeProjects.command("list").description("List time projects with totals and frame usage").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+  output(await getClient().listTimeProjects(opts.org));
+});
+timeProjects.command("show <projectId>").description("One project: setup, person\xD7activity\xD7month matrix, entries with computed split, monthly sheets").option("--org <org>", "Organization slug or id (admin only)").action(async (projectId, opts) => {
+  output(await getClient().getTimeProject(projectId, opts.org));
+});
+timeProjects.command("upsert").description("Create or update a time project from a JSON file (include projectId to update)").requiredOption("--file <path>", "JSON payload with the project setup (- for stdin)").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+  const raw = opts.file === "-" ? (0, import_node_fs8.readFileSync)(0, "utf8") : (0, import_node_fs8.readFileSync)(opts.file, "utf8");
+  const payload = JSON.parse(raw);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("Payload must be a JSON object with the project setup");
+  }
+  output(await getClient().upsertTimeProject(payload, opts.org));
+});
+var timeEntries = time.command("entries").description("Registered hours");
+timeEntries.command("list").description("Flat rows with the computed split (counted, self-financed, reportable, reasons)").option("--project <projectId>", "Only this project").option("--user <userId>", "Only this person (owners and admins)").option("--from <YYYY-MM-DD>", "First work date").option("--to <YYYY-MM-DD>", "Last work date").option("--status <status>", "draft | submitted | approved").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+  output(
+    await getClient().listTimeEntries({
+      project: opts.project,
+      user: opts.user,
+      from: opts.from,
+      to: opts.to,
+      status: opts.status,
+      org: opts.org
+    })
+  );
+});
+timeEntries.command("import").description("Idempotent batch import of hours into one project. Requires --dry-run or --approved").requiredOption("--project <projectId>", "Target time project").requiredOption("--file <path>", "JSON: { entries: [...] } or a bare array (- for stdin)").option("--dry-run", "Validate and report what would happen, write nothing").option("--approved", "The operator approved the dry-run result").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+  if (!opts.dryRun && !opts.approved) {
+    throw new Error(
+      "Refusing to write: run with --dry-run first, show the operator the summary, then repeat with --approved. This writes real hours, not proposals."
+    );
+  }
+  const raw = opts.file === "-" ? (0, import_node_fs8.readFileSync)(0, "utf8") : (0, import_node_fs8.readFileSync)(opts.file, "utf8");
+  const payload = JSON.parse(raw);
+  const entries = Array.isArray(payload) ? payload : payload?.entries;
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error("Payload needs { entries: [...] } with at least one entry");
+  }
+  output(
+    await getClient().importTimeEntries({
+      projectId: opts.project,
+      entries,
+      dryRun: Boolean(opts.dryRun),
+      org: opts.org
+    })
+  );
+});
+var timeMonths = time.command("months").description("Monthly sheets: submit, approve, return, reopen");
+timeMonths.command("list").description("Months waiting for your approval (project owner), or every submitted month (admin)").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+  output(await getClient().listPendingTimeMonths(opts.org));
+});
+for (const action of ["submit", "approve", "return", "reopen"]) {
+  const descriptions = {
+    submit: "Submit a month for approval (your own; admins may pass --user-email)",
+    approve: "Approve a submitted month \u2014 locks its rows (project owner or admin)",
+    return: "Return a submitted month as drafts, --comment required (project owner or admin)",
+    reopen: "Reopen an approved month for correction; it needs a new approval"
+  };
+  timeMonths.command(action).description(descriptions[action]).requiredOption("--project <projectId>", "Time project").requiredOption("--month <YYYY-MM>", "Month").option("--user-email <email>", "Whose month (defaults to yourself)").option("--user <userId>", "Whose month, by user id").option("--comment <text>", "Comment (required for return)").option("--org <org>", "Organization slug or id (admin only)").action(async (opts) => {
+    if (action === "return" && !opts.comment) {
+      throw new Error("--comment is required when returning a month");
+    }
+    output(
+      await getClient().actOnTimeMonth({
+        projectId: opts.project,
+        month: opts.month,
+        action,
+        userId: opts.user,
+        userEmail: opts.userEmail,
+        comment: opts.comment,
+        org: opts.org
+      })
+    );
+  });
+}
 function registerAdminCommands() {
   const cfg = loadConfig();
   if (!cfg.isAdmin) return;

package/dist/client.d.ts

@@ -474,6 +474,42 @@ export declare class DayOfWeekClient {
         }>;
     }): Promise<SharedSkillSummary>;
     archiveSharedSkill(skillId: string): Promise<SharedSkillSummary>;
+    listTimeProjects(org?: string): Promise<{
+        projects: any[];
+    }>;
+    getTimeProject(projectId: string, org?: string): Promise<any>;
+    upsertTimeProject(payload: Record<string, unknown>, org?: string): Promise<{
+        projectId: string;
+    }>;
+    listTimeEntries(opts?: {
+        project?: string;
+        user?: string;
+        from?: string;
+        to?: string;
+        status?: string;
+        org?: string;
+    }): Promise<{
+        total: number;
+        rows: any[];
+    }>;
+    importTimeEntries(input: {
+        projectId: string;
+        entries: unknown[];
+        dryRun: boolean;
+        org?: string;
+    }): Promise<any>;
+    listPendingTimeMonths(org?: string): Promise<{
+        approvals: any[];
+    }>;
+    actOnTimeMonth(input: {
+        projectId: string;
+        month: string;
+        action: "submit" | "approve" | "return" | "reopen";
+        userId?: string;
+        userEmail?: string;
+        comment?: string;
+        org?: string;
+    }): Promise<any>;
     getSchema(): Promise<any>;
     private get;
     private post;

package/dist/client.js

@@ -678,6 +678,59 @@ export class DayOfWeekClient {
     async archiveSharedSkill(skillId) {
         return this.delete(`/brain/skills/${encodeURIComponent(skillId)}`);
     }
+    // ── Time tracking ─────────────────────────────────────────────────────────
+    //
+    // Hours registered against time projects. Every rule (periods, frames,
+    // self-financing, the reportable basis, who may approve) is evaluated by
+    // the server; the client only carries JSON and prints what comes back.
+    async listTimeProjects(org) {
+        const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+        return this.get(`/time/projects${qs}`);
+    }
+    async getTimeProject(projectId, org) {
+        const params = new URLSearchParams({ id: projectId });
+        if (org)
+            params.set("org", org);
+        return this.get(`/time/projects?${params.toString()}`);
+    }
+    async upsertTimeProject(payload, org) {
+        const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+        return this.post(`/time/projects${qs}`, payload);
+    }
+    async listTimeEntries(opts) {
+        const params = new URLSearchParams();
+        if (opts?.project)
+            params.set("project", opts.project);
+        if (opts?.user)
+            params.set("user", opts.user);
+        if (opts?.from)
+            params.set("from", opts.from);
+        if (opts?.to)
+            params.set("to", opts.to);
+        if (opts?.status)
+            params.set("status", opts.status);
+        if (opts?.org)
+            params.set("org", opts.org);
+        const qs = params.toString();
+        return this.get(`/time/entries${qs ? `?${qs}` : ""}`);
+    }
+    async importTimeEntries(input) {
+        const qs = input.org ? `?org=${encodeURIComponent(input.org)}` : "";
+        return this.post(`/time/entries${qs}`, {
+            projectId: input.projectId,
+            dryRun: input.dryRun,
+            entries: input.entries,
+        });
+    }
+    async listPendingTimeMonths(org) {
+        const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+        return this.get(`/time/months${qs}`);
+    }
+    async actOnTimeMonth(input) {
+        const { org, ...body } = input;
+        const qs = org ? `?org=${encodeURIComponent(org)}` : "";
+        return this.post(`/time/months${qs}`, body);
+    }
     // ── Schema ────────────────────────────────────────────────────────────────
     async getSchema() {
         return this.get("/schema");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dayofweek/dcli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "CLI for the Day of Week AgTech platform — read data and submit proposals for review",
   "license": "MIT",
   "type": "module",