@srafis/zsync 0.1.6 → 0.1.8

package/LICENCE

@@ -0,0 +1,9 @@
+# MIT Licence
+
+Copyright 2026 Kamaljot Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -11,7 +11,7 @@ You need:
 - Node.js 22 or newer
 - An interactive terminal
 - A Clockify account with time entries
-- A Zoho People account with Time Tracker access and at least one assigned job
+- A Zoho People account with Time Tracker access, at least one assigned project, and permission to create and assign jobs
 
 Install the published package:
 
@@ -42,9 +42,10 @@ Before you configure zsync, collect these values:
 - A Clockify API key, user ID, and workspace ID
 - A Zoho client ID and client secret
 - Access to Zoho People Time Tracker
-- A Zoho job assigned to your employee record
+- Zoho projects assigned to your employee record. Matching names help zsync map them automatically.
+- Permission to create and assign jobs in Zoho People
 
-Use the same Clockify user and workspace that own the entries you want to sync. zsync checks both values before it reads your time entries.
+Use the Clockify user and workspace that contain the entries you want to sync. zsync checks both values before it reads your time entries.
 
 ## Configure zsync
 
@@ -70,7 +71,7 @@ Keep these values private. Do not commit them to a repository. The published com
 | `ZOHO_REGION`        | Zoho data center code: `com`, `eu`, `in`, `au`, `cn`, `jp`, `ca`, `sa`, or `uk` | Saved region, otherwise `com`                     |
 | `ZSYNC_TIMEZONE`     | Time zone used for entry dates, such as `Asia/Kolkata`                          | System time zone                                  |
 | `ZOHO_DATE_FORMAT`   | Date format used by your Zoho organization                                      | `yyyy-MM-dd`                                      |
-| `ZSYNC_STATE_DIR`    | Folder for saved authentication and job mappings                                | See [Saved files](#saved-files)                   |
+| `ZSYNC_STATE_DIR`    | Folder for saved authentication and project mappings                            | See [Saved files](#saved-files)                   |
 | `ZOHO_REFRESH_TOKEN` | Use an existing Zoho refresh token                                              | Saved token                                       |
 | `ZOHO_EMPLOYEE_ID`   | Set the Zoho employee record ID, also called `ERECNO`                           | Saved ID, otherwise looked up after authorization |
 
@@ -109,7 +110,7 @@ To authorize again, run:
 zsync --connect
 ```
 
-Reconnecting keeps saved job mappings for the same account.
+Reconnecting keeps saved project mappings for the same account.
 
 ## Sync your time
 
@@ -123,44 +124,46 @@ Use the prompts in this order:
 
 1. Choose Today, Yesterday, This week, Last week, or This month.
 2. Use the arrow keys to move through the entries. Press Space to select or clear an entry. Press Enter to continue. Press Esc to cancel.
-3. Choose a Zoho job for each Clockify project that has no saved match. zsync selects a unique project or job with the same name when it can.
-4. Review the create, update, and delete counts.
-5. Choose Yes to write the changes.
+3. Choose a Zoho project for each Clockify project that has neither a saved mapping nor a unique case-insensitive name match.
+4. zsync uses the alphabetically first Clockify tag as the Zoho job, reusing a case-insensitive match or creating the job under the selected project. Entries without tags use the `N/A` job.
+5. Review the create, update, job creation, and delete counts.
+6. Choose Yes to write the changes.
 
-New, changed, and deleted entries start selected. Unchanged entries that zsync already synced are not selected. Changed entries show `[updated]` before the description. Deleted entries show `[deleted]`.
+New, changed, and deleted entries start selected. Unchanged entries that zsync already synced are not selected. Changed entries show `[U]` before the description. Deleted entries show `[D]`.
 
-The final prompt defaults to Yes when it only creates or updates entries. It defaults to No when it includes a deletion. zsync makes no Zoho changes before this final confirmation. It may save job mappings before you confirm.
+The final prompt defaults to Yes when it only creates or updates entries. It defaults to No when it includes a deletion. zsync makes no Zoho changes before this final confirmation. It may save project mappings before you confirm.
 
 Weeks start on Monday. Today, This week, and This month end at the time you start zsync. zsync uses `ZSYNC_TIMEZONE` for local dates.
 
 ## What zsync copies
 
 
-| Clockify data                                                                | Zoho People result                                   |
-| ---------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Description                                                                  | Work Item                                            |
-| Project                                                                      | The Zoho job you select or zsync matches             |
-| Duration                                                                     | Hours, rounded to the nearest minute                 |
-| Start date                                                                   | Work date in your configured time zone               |
-| Billable flag                                                                | Billing status                                       |
-| Entry ID, project, tags, timestamps, billing flag, workspace ID, and user ID | Readable metadata in Description, with a sync marker |
+| Clockify data                                                                | Zoho People result                                                         |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Description                                                                  | Work Item                                                                  |
+| Project                                                                      | The Zoho project you select or zsync matches                               |
+| Tags                                                                         | A Zoho job under that project; alphabetically first tag, or `N/A` when empty |
+| Duration                                                                     | Hours, rounded to the nearest minute                                       |
+| Start date                                                                   | Work date in your configured time zone                                     |
+| Billable flag                                                                | Billing status                                                             |
+| Entry ID, project, tags, timestamps, billing flag, workspace ID, and user ID | Readable metadata in the Description, with a sync marker                   |
 
 
-Only completed entries are included. zsync creates duration-based logs. It does not create Zoho projects or jobs.
+Only completed entries are included. zsync creates duration-based logs and missing tag jobs. It does not create Zoho projects.
 
 An entry belongs to the local date of its start time. If an entry crosses midnight, zsync copies the full duration to that start date. Entries longer than 24 hours or entries that round to less than one minute must be corrected in Clockify first.
 
 ## Run a sync again
 
-zsync writes readable source metadata and a marker such as `[zsync-source:...]` in each Zoho log description. It uses this data to find the log that belongs to a Clockify entry. Keep the metadata and marker in the description.
+zsync writes readable source metadata and a marker such as `[zsync-source:...]` in each Zoho log description. It uses this data to find the log that belongs to a Clockify entry. Keep the metadata and marker in the description. All Clockify tags remain in the metadata even when only one tag selects the Zoho job.
 
-If a Clockify entry changed, select its `[updated]` row. zsync then writes the current Clockify values to the matching Zoho log. A Zoho log that you entered by hand has no source metadata, so zsync does not treat it as a match. If you delete a synced Zoho log, its Clockify entry appears as new on the next run.
+If a Clockify entry or its tags changed, select its `[U]` row. zsync then writes the current Clockify values and selected Zoho project and job to the matching Zoho log. A Zoho log that you entered by hand has no source metadata, so zsync does not treat it as a match. If you delete a synced Zoho log, its Clockify entry appears as new on the next run.
 
 Before each write, zsync checks both services again. It verifies the result after the write. A run can finish with both successful and failed entries. If a result is uncertain, inspect Zoho People before you retry it.
 
 ## Review deleted entries
 
-Before it shows the selection table, zsync checks synced Zoho logs in the selected date range. If the source entry no longer exists in Clockify, the Zoho log appears with `[deleted]` and is selected by default.
+Before it shows the selection table, zsync checks synced Zoho logs in the selected date range. If the source entry no longer exists in Clockify, the Zoho log appears with `[D]` and is selected by default.
 
 You can clear a deletion to keep the Zoho log. zsync checks each selected deletion and its Clockify source again before it deletes the log. It does not offer an entry that still exists in Clockify, even if the entry moved to another date. It also excludes manual, locked, and ambiguous Zoho logs.
 
@@ -175,13 +178,13 @@ zsync applies creates and updates before deletions. A failed operation does not
 - If you move a synced entry outside the selected date range, include the old Zoho log date in a later run when you clean it up.
 - Run one sync at a time. zsync does not coordinate runs from different terminals or machines.
 - zsync uses `api.clockify.me`. Clockify regional API endpoints are not supported.
-- Zoho attendance rules, date rules, and job permissions can reject a write.
+- Zoho attendance rules, date rules, project assignments, and job permissions can reject a write.
 
 
 
 ## Saved files
 
-zsync stores authentication and job mappings on your computer. It stores them per account.
+zsync stores authentication and project mappings on your computer. It stores them per account.
 
 
 | System  | Default folder                                    |
@@ -197,7 +200,8 @@ The authentication file contains a refresh token and employee record ID. zsync c
 
 - `Missing required environment variable`: set all five required variables in the current terminal.
 - `Clockify API key does not belong to CLOCKIFY_USER_ID`: use the user ID that belongs to the API key.
-- `No eligible Zoho jobs`: ask your Zoho People administrator to assign an active job to your employee record.
+- `No eligible Zoho projects`: ask your Zoho People administrator to create or assign an active project.
+- Job creation errors: ask your Zoho People administrator for permission to create and assign jobs.
 - `Port 8765 may be in use`: stop the other local process and run zsync again.
 - `Zoho authorization expired or was revoked`: run `zsync --connect`.
 
@@ -229,4 +233,4 @@ bun run build
 bun pm pack
 ```
 
-The build creates `dist/zsync.js`, a Node.js 22 or newer executable. Tests use fictional API responses and do not create real time logs.
+The build creates `dist/zsync.js`, a Node.js 22 or newer executable. Tests use fictional API responses and do not create real time logs.

package/dist/zsync.js

@@ -5701,7 +5701,7 @@ function dateRange(name, zone, now = qi.Now.instant().toString()) {
     lastDate: qi.PlainDate.compare(first, end.subtract({ nanoseconds: 1 }).toZonedDateTimeISO(zone).toPlainDate()) > 0 ? first.toString() : end.subtract({ nanoseconds: 1 }).toZonedDateTimeISO(zone).toPlainDate().toString()
   };
 }
-function entryInput(entry, jobId, employeeId, zone, source) {
+function entryInput(entry, projectId, jobId, employeeId, zone, source) {
   const start = qi.Instant.from(entry.start);
   const end = qi.Instant.from(entry.end);
   const seconds = Number(end.epochNanoseconds - start.epochNanoseconds) / 1e9;
@@ -5712,6 +5712,7 @@ function entryInput(entry, jobId, employeeId, zone, source) {
   if (minutes < 1)
     throw new Error(`Entry ${entry.id} rounds to zero minutes. Adjust it in Clockify before syncing.`);
   return {
+    projectId,
     jobId,
     employeeId,
     date: start.toZonedDateTimeISO(zone).toPlainDate().toString(),
@@ -5773,7 +5774,7 @@ function isDate(value) {
   return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
 }
 function validateInput(value, label, minimumMinutes = 1) {
-  if (!isRecord2(value) || typeof value.jobId !== "string" || !value.jobId || typeof value.employeeId !== "string" || !value.employeeId || !isDate(value.date) || typeof value.minutes !== "number" || !Number.isInteger(value.minutes) || value.minutes < minimumMinutes || value.minutes > 1440 || value.workItem !== undefined && typeof value.workItem !== "string" || typeof value.description !== "string" || typeof value.billable !== "boolean") {
+  if (!isRecord2(value) || typeof value.projectId !== "string" || !value.projectId || typeof value.jobId !== "string" || !value.jobId || typeof value.employeeId !== "string" || !value.employeeId || !isDate(value.date) || typeof value.minutes !== "number" || !Number.isInteger(value.minutes) || value.minutes < minimumMinutes || value.minutes > 1440 || value.workItem !== undefined && typeof value.workItem !== "string" || typeof value.description !== "string" || typeof value.billable !== "boolean") {
     throw new Error(`${label} is not a valid log input`);
   }
 }
@@ -5807,6 +5808,7 @@ function markedInput(input, marker) {
 }
 function comparable(input) {
   return {
+    projectId: input.projectId,
     jobId: input.jobId,
     employeeId: input.employeeId,
     date: input.date,
@@ -5820,12 +5822,13 @@ function sameFields(left, right) {
   return JSON.stringify(comparable(left)) === JSON.stringify(comparable(right));
 }
 function samePlannedFields(remote, input) {
-  if (input.jobId !== "__unmapped__")
-    return sameFields(remote, input);
-  return sameFields(remote, { ...input, jobId: remote.jobId });
+  if (input.projectId === "__unmapped__" || input.jobId === "__unmapped__")
+    return false;
+  return sameFields(remote, input);
 }
 function remoteSnapshot(logs) {
   return JSON.stringify([...logs].map((log) => ({
+    projectId: log.projectId,
     jobId: log.jobId,
     employeeId: log.employeeId,
     date: log.date,
@@ -5875,34 +5878,33 @@ function contextFor(store) {
 async function openStore(directory, scope) {
   await mkdir2(directory, { recursive: true, mode: 448 });
   const hash = createHash3("sha256").update(scope).digest("hex").slice(0, 32);
-  const path = join3(directory, `zsync-preferences-${hash}.json`);
-  let mappings = {};
-  for (const candidate of [path, join3(directory, `zsync-state-${hash}.json`)]) {
-    let text;
-    try {
-      text = await readFile2(candidate, "utf8");
-    } catch (error) {
-      if (error.code === "ENOENT")
-        continue;
+  const path = join3(directory, `zsync-project-preferences-${hash}.json`);
+  let projectMappings = {};
+  let text;
+  try {
+    text = await readFile2(path, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT")
       throw error;
-    }
+    text = "";
+  }
+  if (text) {
     let data;
     try {
       data = JSON.parse(text);
     } catch {
-      throw new Error(`Invalid job preferences at ${candidate}`);
+      throw new Error(`Invalid project preferences at ${path}`);
     }
-    if (data.scope !== scope || !isRecord2(data.mappings) || Object.values(data.mappings).some((v) => typeof v !== "string" || !v))
-      throw new Error(`Invalid job preferences at ${candidate}`);
-    mappings = { ...data.mappings };
-    break;
+    if (data.scope !== scope || !isRecord2(data.projectMappings) || Object.values(data.projectMappings).some((v) => typeof v !== "string" || !v))
+      throw new Error(`Invalid project preferences at ${path}`);
+    projectMappings = { ...data.projectMappings };
   }
   const context = { scope, closed: false };
   const store = {
-    mappings,
+    projectMappings,
     saveMappings: async () => {
       contextFor(store);
-      await writeAtomic(path, { scope, mappings: store.mappings });
+      await writeAtomic(path, { scope, projectMappings: store.projectMappings });
     },
     close: async () => {
       context.closed = true;
@@ -6148,13 +6150,26 @@ async function demoServices() {
   }];
   entries.push({ ...entries[0], id: "demo-entry-2", description: "Already synced example", tags: [] });
   const logs = new Map;
+  const projects = [{ id: "demo-zoho-project", name: "Example project" }];
+  const jobs = [
+    { id: "demo-meeting-job", name: "Meeting", projectId: "demo-zoho-project", projectName: "Example project" },
+    { id: "demo-na-job", name: "N/A", projectId: "demo-zoho-project", projectName: "Example project" }
+  ];
   const zoho = {
     async deleteLog(id) {
       logs.delete(id);
     },
     async validate() {},
+    async listProjects() {
+      return projects.map((project) => ({ ...project }));
+    },
     async listJobs() {
-      return [{ id: "demo-job", name: "Example project" }];
+      return jobs.map((job) => ({ ...job }));
+    },
+    async createJob(name, projectId) {
+      const job = { id: `demo-job-${jobs.length + 1}`, name, projectId };
+      jobs.push(job);
+      return job;
     },
     async listLogs() {
       return [...logs.values()].map((log) => ({ ...log }));
@@ -6174,9 +6189,9 @@ async function demoServices() {
   };
   const store = await openStore(stateDir, accountScope(config));
   try {
-    await commit(store, zoho, await prepare(store, zoho, [{ key: entries[1].id, input: entryInput(entries[1], "demo-job", "demo", "UTC", { workspaceId: "demo", userId: "demo" }) }]));
+    await commit(store, zoho, await prepare(store, zoho, [{ key: entries[1].id, input: entryInput(entries[1], "demo-zoho-project", "demo-na-job", "demo", "UTC", { workspaceId: "demo", userId: "demo" }) }]));
     const deleted = { ...entries[0], id: "demo-deleted", description: "Deleted Clockify example" };
-    await commit(store, zoho, await prepare(store, zoho, [{ key: deleted.id, input: entryInput(deleted, "demo-job", "demo", "UTC", { workspaceId: "demo", userId: "demo" }) }]));
+    await commit(store, zoho, await prepare(store, zoho, [{ key: deleted.id, input: entryInput(deleted, "demo-zoho-project", "demo-meeting-job", "demo", "UTC", { workspaceId: "demo", userId: "demo" }) }]));
   } finally {
     await store.close();
   }
@@ -7784,6 +7799,7 @@ function remoteLog(raw, config, context) {
   const locked = raw.locked === true || raw.locked === "true" || approvalStatus === "approved" || approvalStatus === "pending" || editAllowed === false || editAllowed === "false";
   return {
     id: valueId(raw.timelogId, "timelogId", context),
+    projectId: raw.projectId === undefined || raw.projectId === null ? "__unmapped__" : valueId(raw.projectId, "projectId", context),
     jobId: valueId(raw.jobId, "jobId", context),
     employeeId,
     date: parseZohoDate(raw.workDate, config.zohoDateFormat ?? "yyyy-MM-dd", context, raw.db_workDate),
@@ -7798,8 +7814,8 @@ function logFields(input, config) {
   if (input.employeeId !== config.zohoEmployeeId)
     throw new Error("Zoho log employeeId does not match configured employee");
   validDate(input.date, "log date");
-  if (!input.jobId || !Number.isInteger(input.minutes) || input.minutes < 1 || input.minutes > MAX_MINUTES) {
-    throw new Error("Zoho log requires a job and 1-1440 whole minutes");
+  if (!input.projectId || !input.jobId || !Number.isInteger(input.minutes) || input.minutes < 1 || input.minutes > MAX_MINUTES) {
+    throw new Error("Zoho log requires a project, job, and 1-1440 whole minutes");
   }
   if (typeof input.description !== "string" || input.description.length > 15000)
     throw new Error("Zoho log description is malformed or too long");
@@ -7810,6 +7826,7 @@ function logFields(input, config) {
   const format = dateFormat(config.zohoDateFormat ?? "yyyy-MM-dd");
   return {
     user: input.employeeId,
+    projectId: input.projectId,
     jobId: input.jobId,
     workDate: formatDate(input.date, format),
     dateFormat: format,
@@ -7880,8 +7897,42 @@ function createZoho(config, options = {}) {
     const body = await zohoRequest(queryUrl("", path, params));
     return zohoStatus(body, `Zoho ${path}`, secrets);
   }
+  const projectsRate = { lastAt: 0, queue: Promise.resolve() };
   const jobsRate = { lastAt: 0, queue: Promise.resolve() };
   const logsRate = { lastAt: 0, queue: Promise.resolve() };
+  async function listProjects() {
+    const projects = [];
+    for (let index = 0;; ) {
+      const response = await rateLimit(projectsRate, ZOHO_WRITE_INTERVAL_MS, sleep, () => zohoPage("/timetracker/getprojects", {
+        assignedTo: config.zohoEmployeeId,
+        projectStatus: "inprogress",
+        sIndex: String(index),
+        limit: String(PAGE_SIZE)
+      }));
+      if (!Array.isArray(response.result) || !response.result.every(isRecord))
+        throw new Error("Zoho getprojects returned malformed result");
+      for (const raw of response.result)
+        projects.push({
+          id: valueId(raw.projectId, "projectId", "Zoho project"),
+          name: valueString(raw.projectName, "projectName", "Zoho project")
+        });
+      if (!boolValue(response.isNextAvailable) || response.result.length === 0)
+        return projects;
+      index += response.result.length;
+    }
+  }
+  async function createJob(name, projectId) {
+    const jobName = name.trim();
+    if (!jobName || !projectId)
+      throw new Error("Zoho job requires a name and project");
+    const inputData = JSON.stringify({ Job_Name: jobName, Project: projectId, Assignees: config.zohoEmployeeId });
+    const body = await rateLimit(jobsRate, ZOHO_WRITE_INTERVAL_MS, sleep, () => zohoRequest("/forms/json/P_TimesheetJob/insertRecord", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: formBody({ inputData }) }, true));
+    const response = zohoStatus(body, "Zoho create job", secrets, true);
+    const result = Array.isArray(response.result) ? response.result[0] : response.result;
+    if (!isRecord(result))
+      throw new Error("Zoho create job returned malformed result; write outcome may be uncertain");
+    return { id: valueId(result.pkId, "pkId", "Zoho create job"), name: jobName, projectId };
+  }
   async function listJobs() {
     const jobs = [];
     for (let index = 0;; ) {
@@ -7898,7 +7949,11 @@ function createZoho(config, options = {}) {
         const status = typeof raw.jobStatus === "string" ? raw.jobStatus.toLowerCase() : "";
         if (status.includes("completed") || status.includes("inactive"))
           continue;
-        const job = { id: valueId(raw.jobId, "jobId", "Zoho job"), name: valueString(raw.jobName, "jobName", "Zoho job") };
+        const job = {
+          id: valueId(raw.jobId, "jobId", "Zoho job"),
+          name: valueString(raw.jobName, "jobName", "Zoho job"),
+          projectId: raw.projectId === undefined || raw.projectId === null ? "__unmapped__" : valueId(raw.projectId, "projectId", "Zoho job")
+        };
         if (raw.projectName !== undefined) {
           if (typeof raw.projectName !== "string")
             throw new Error("Zoho job projectName is malformed");
@@ -7987,12 +8042,12 @@ function createZoho(config, options = {}) {
     });
   }
   return { validate: async () => {
-    await listJobs();
-  }, listJobs, listLogs, getLog, createLog, updateLog, deleteLog };
+    await Promise.all([listProjects(), listJobs()]);
+  }, listProjects, listJobs, createJob, listLogs, getLog, createLog, updateLog, deleteLog };
 }
 
 // src/auth.ts
-var scopes = "ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.forms.READ,AaaServer.profile.READ";
+var scopes = "ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.forms.READ,ZOHOPEOPLE.forms.CREATE,AaaServer.profile.READ";
 var redirect = "http://localhost:8765/callback";
 function answer(value) {
   if (isCancel(value))
@@ -8251,7 +8306,7 @@ function entryTable(rows, columns) {
   if (columns >= 110)
     fields.push({ title: "Tags", size: 14, value: (row) => row.entry.tags.join("/") || "—" });
   const used = fields.reduce((sum, field) => sum + field.size + 3, 0);
-  fields.push({ title: "Description", size: Math.max(1, available - used), value: (row) => `${row.status === "changed" || row.status === "deleted" ? `[${row.status === "changed" ? "updated" : "deleted"}] ` : ""}${row.entry.description || "—"}` });
+  fields.push({ title: "Description", size: Math.max(1, available - used), value: (row) => `${row.status === "changed" || row.status === "deleted" ? `[${row.status === "changed" ? "U" : "D"}] ` : ""}${row.entry.description || "—"}` });
   const line = (cells) => fitCell(cells.join(" │ "), available).trimEnd();
   return {
     header: line(fields.map((field) => fitCell(field.title, field.size))),
@@ -8260,7 +8315,7 @@ function entryTable(rows, columns) {
   };
 }
 function colorEntryLabel(label, dim = false) {
-  return label.split(/(\[updated\]|\[deleted\])/).map((part) => part === "[updated]" ? styleText3(["bold", "yellow"], part) : part === "[deleted]" ? styleText3(["bold", "red"], part) : dim ? styleText3("dim", part) : part).join("");
+  return label.split(/(\[U\]|\[D\])/).map((part) => part === "[U]" ? styleText3(["bold", "yellow"], part) : part === "[D]" ? styleText3(["bold", "red"], part) : dim ? styleText3("dim", part) : part).join("");
 }
 function pickEntries(rows) {
   return new a({
@@ -8349,11 +8404,22 @@ async function busy(message, action) {
     clearLine2(process.stdout, 0);
   }
 }
-function automaticJob(entry, jobs) {
+var FALLBACK_JOB = "N/A";
+function tagJobName(tags) {
+  const names = tags.map((tag) => tag.trim()).filter(Boolean);
+  names.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()) || a.localeCompare(b));
+  return names[0] ?? FALLBACK_JOB;
+}
+function matchingJob(projectId, name, jobs) {
+  const wanted = name.trim().toLowerCase();
+  return jobs.find((job) => job.projectId === projectId && job.name.trim().toLowerCase() === wanted);
+}
+function automaticProject(entry, projects) {
   if (!entry.projectId)
     return;
-  const matches = jobs.filter((job) => job.projectName === entry.projectName || job.name === entry.projectName);
-  return matches.length === 1 ? matches[0].id : undefined;
+  const wanted = entry.projectName.trim().toLowerCase();
+  const matches = projects.filter((project) => project.name.trim().toLowerCase() === wanted);
+  return matches.length === 1 ? matches[0] : undefined;
 }
 async function main(argv = process.argv.slice(2)) {
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -8409,14 +8475,21 @@ Optional: ZOHO_REFRESH_TOKEN, ZOHO_EMPLOYEE_ID, ZOHO_REGION, ZSYNC_TIMEZONE, ZSY
     }
     const scope = accountScope(config);
     store = await openStore(config.stateDir, scope);
-    const jobs = await busy("Fetching Zoho People jobs", () => zoho.listJobs());
+    const projects = await busy("Fetching Zoho People projects", () => zoho.listProjects());
+    let jobs = await busy("Fetching Zoho People jobs", () => zoho.listJobs());
+    const projectFor = (entry) => {
+      if (!entry.projectId)
+        return;
+      const saved = store.projectMappings[entry.projectId];
+      return projects.find((project) => project.id === saved) ?? automaticProject(entry, projects);
+    };
     const jobFor = (entry) => {
-      const saved = store.mappings[entry.projectId ?? "(no project)"];
-      return jobs.some((job) => job.id === saved) ? saved : automaticJob(entry, jobs);
+      const project = projectFor(entry);
+      return project ? matchingJob(project.id, tagJobName(entry.tags), jobs) : undefined;
     };
     const makeInputs = (items) => items.map((entry) => ({
       key: entry.id,
-      input: entryInput(entry, jobFor(entry) ?? "__unmapped__", config.zohoEmployeeId, config.timezone, { workspaceId: config.clockifyWorkspaceId, userId: config.clockifyUserId })
+      input: entryInput(entry, projectFor(entry)?.id ?? "__unmapped__", jobFor(entry)?.id ?? "__unmapped__", config.zohoEmployeeId, config.timezone, { workspaceId: config.clockifyWorkspaceId, userId: config.clockifyUserId })
     }));
     const initialPlan = await busy("Checking sync status", () => prepare(store, zoho, makeInputs(entries)));
     const initialByKey = new Map(initialPlan.map((item) => [item.key, item]));
@@ -8426,7 +8499,7 @@ Optional: ZOHO_REFRESH_TOKEN, ZOHO_EMPLOYEE_ID, ZOHO_REGION, ZSYNC_TIMEZONE, ZSY
         entry,
         input: item.input,
         status: item.status === "create" ? "new" : item.status === "skip" ? "synced" : item.status === "update" ? "changed" : "conflict",
-        reason: item.reason ?? (!jobFor(entry) ? "Choose a Zoho job after selection" : undefined)
+        reason: item.reason ?? (!entry.projectId ? "Assign a Clockify project before syncing" : !projectFor(entry) ? "Choose a Zoho project after selection" : !jobFor(entry) ? `Creates Zoho job "${tagJobName(entry.tags)}" after confirmation` : undefined)
       };
     }), ...deletions.map(({ log: log2, entryId }) => ({
       entry: {
@@ -8451,23 +8524,30 @@ Optional: ZOHO_REFRESH_TOKEN, ZOHO_EMPLOYEE_ID, ZOHO_REGION, ZSYNC_TIMEZONE, ZSY
       outro("Nothing selected. No Zoho changes.");
       return;
     }
-    if (selected.length && !jobs.length)
-      throw new Error("No eligible Zoho jobs. Ask your People administrator to assign a job first.");
-    for (const entry of selected) {
-      const key = entry.projectId ?? "(no project)";
-      if (!jobFor(entry)) {
-        store.mappings[key] = answer2(await select({
-          message: `Zoho job for ${cleanText(entry.projectName || "entries without a project")}?`,
-          options: jobs.map((job) => ({
-            value: job.id,
-            label: cleanText(`${job.projectName ? job.projectName + " / " : ""}${job.name}`),
-            hint: job.id
-          }))
-        }));
-      } else
-        store.mappings[key] = jobFor(entry);
+    if (selected.length) {
+      if (!projects.length)
+        throw new Error("No eligible Zoho projects. Ask your People administrator to create or assign a project first.");
+      for (const entry of selected) {
+        if (!entry.projectId)
+          throw new Error(`Clockify entry ${entry.id} has no project. Assign it in Clockify before syncing.`);
+        const project = projectFor(entry);
+        if (!project) {
+          store.projectMappings[entry.projectId] = answer2(await select({
+            message: `Zoho project for ${cleanText(entry.projectName)}?`,
+            options: projects.map((project) => ({ value: project.id, label: cleanText(project.name), hint: project.id }))
+          }));
+        } else
+          store.projectMappings[entry.projectId] = project.id;
+      }
     }
     await store.saveMappings();
+    const jobsToCreate = new Map;
+    for (const entry of selected) {
+      const project = projectFor(entry);
+      const name = tagJobName(entry.tags);
+      if (!matchingJob(project.id, name, jobs))
+        jobsToCreate.set(`${project.id}\x00${name.toLowerCase()}`, { name, projectId: project.id });
+    }
     const plan = await busy("Preparing commit", () => prepare(store, zoho, makeInputs(selected)));
     const conflicts = plan.filter((item) => item.status === "conflict");
     if (conflicts.length) {
@@ -8476,7 +8556,7 @@ Optional: ZOHO_REFRESH_TOKEN, ZOHO_EMPLOYEE_ID, ZOHO_REGION, ZSYNC_TIMEZONE, ZSY
       throw new Error("Resolve the conflicts or deselect those entries, then rerun. No selected logs were written.");
     }
     const confirmed = answer2(await select({
-      message: `Create ${plan.filter((item) => item.status === "create").length}, update ${plan.filter((item) => item.status === "update").length}, delete ${selectedDeletions.length} Zoho entries?`,
+      message: `Create ${plan.filter((item) => item.status === "create").length}, update ${plan.filter((item) => item.status === "update").length}, create ${jobsToCreate.size} Zoho jobs, delete ${selectedDeletions.length} entries?`,
       initialValue: selectedDeletions.length === 0,
       options: [
         { value: true, label: "Yes" },
@@ -8487,13 +8567,30 @@ Optional: ZOHO_REFRESH_TOKEN, ZOHO_EMPLOYEE_ID, ZOHO_REGION, ZSYNC_TIMEZONE, ZSY
       outro("Cancelled. No Zoho changes.");
       return;
     }
+    if (jobsToCreate.size) {
+      await busy("Creating Zoho jobs", async () => {
+        for (const request of jobsToCreate.values()) {
+          const existing = matchingJob(request.projectId, request.name, jobs);
+          if (existing)
+            continue;
+          jobs.push(await zoho.createJob(request.name, request.projectId));
+        }
+      });
+    }
+    const finalPlan = await busy("Preparing commit", () => prepare(store, zoho, makeInputs(selected)));
+    const finalConflicts = finalPlan.filter((item) => item.status === "conflict");
+    if (finalConflicts.length) {
+      for (const item of finalConflicts)
+        log.error(`${item.key}: ${cleanText(item.reason ?? "Needs reconciliation")}`);
+      throw new Error("Resolve the conflicts or rerun. No selected logs were written.");
+    }
     const fresh = await busy("Rechecking Clockify entries", () => clockify.listEntries(range.start, range.end));
     for (const entry of selected) {
       const current = fresh.find((item) => item.id === entry.id);
       if (!current || JSON.stringify(current) !== JSON.stringify(entry))
         throw new Error(`Clockify entry ${entry.id} changed. Rerun to review the updated plan; no writes made.`);
     }
-    const results = await busy("Syncing selected entries", () => commit(store, zoho, plan));
+    const results = await busy("Syncing selected entries", () => commit(store, zoho, finalPlan));
     for (const item of selectedDeletions) {
       try {
         await busy("Deleting selected Zoho entry", () => deleteConfirmed(item, clockify, zoho));

package/docs/clockify-setup.md

@@ -2,34 +2,39 @@
 
 zsync needs a Clockify API key, user ID, and workspace ID.
 
-Use the same user, API key, and workspace together. zsync reads entries for that user only.
+Use the same user, API key, and workspace. zsync reads entries for that user only.
 
 ## Create an API key
 
 1. Sign in to Clockify.
-2. Open your account menu.
-3. Select Preferences, then Advanced.
-4. In the API Key section, select Generate.
-5. Copy the key and store it in a safe place. Clockify does not show it again after you close the window.
+2. Open [Manage API keys](https://app.clockify.me/manage-api-keys).
+3. Click the `GENERATE NEW` button, give it a name, and click `GENERATE`.
+4. Copy the key and save it in your shell configuration file:
+
+   ```sh
+   export CLOCKIFY_API_KEY="..."
+   ```
+
+> [!NOTE]
+> Clockify does not show the API key again after you close the window.
 
 See Clockify's [API and webhook settings](https://clockify.me/help/administration/api-webhook-settings) for the current menu names.
 
-## Find your user ID
+## Find your user ID and workspace ID
 
-The user ID is different from the API key. The endpoint below returns the user for the API key:
+Make sure `CLOCKIFY_API_KEY` is set in the current shell. This command also requires `jq`:
 
 ```sh
-curl -sS -H "X-Api-Key: $CLOCKIFY_API_KEY" https://api.clockify.me/api/v1/user
+curl -sS -H "X-Api-Key: $CLOCKIFY_API_KEY" \
+  https://api.clockify.me/api/v1/user |
+jq -r '"export CLOCKIFY_USER_ID=\"\(.id)\"\nexport CLOCKIFY_WORKSPACE_ID=\"\(.defaultWorkspace)\""'
 ```
 
-Use the `id` value in the response as `CLOCKIFY_USER_ID`. See Clockify's [user ID instructions](https://clockify.me/help/troubleshooting/how-to-find-userid-in-the-api) for other ways to find it.
-
-## Find your workspace ID
-
-Open the workspace in Clockify. Its URL contains `/workspaces/<workspace-id>`. Copy the value after `/workspaces/` and use it as `CLOCKIFY_WORKSPACE_ID`.
+Example expected output:
 
-Use the workspace where you track the time. zsync uses the default Clockify API endpoint, `https://api.clockify.me/api/v1`. Clockify regional API endpoints are not supported.
-
-## Keep the key safe
+```sh
+export CLOCKIFY_USER_ID="..."
+export CLOCKIFY_WORKSPACE_ID="..."
+```
 
-Do not commit the API key to a repository. If you delete the key in Clockify, zsync cannot access your entries until you create and configure a new one.
+Store these in your shell configuration file (`~/.bashrc`/`~/.zshrc`).

package/docs/zoho-setup.md

@@ -1,21 +1,22 @@
 # Set up Zoho People
 
-zsync needs a Zoho OAuth client, Time Tracker API access, and a job assigned to your employee record.
+zsync needs a Zoho OAuth client, Time Tracker API access, an active project assigned to your employee record, and permission to create and assign jobs.
 
 ## Create an OAuth client
 
-1. Open the [Zoho People OAuth instructions](https://www.zoho.com/people/api/oauth-steps.html).
-2. Open the Zoho API Console from that page.
-3. Create a server-based application. Zoho may call this client type Web-based.
-4. Choose the data center that contains your Zoho People account.
-5. Register this redirect URI exactly:
-
-   ```text
-   http://localhost:8765/callback
+1. Open the [Zoho API Console](https://api-console.zoho.com/add#web) in a browser where you are logged in to Zoho People.
+2. Enter `@srafis/zsync` as the client name.
+3. Set `http://localhost:8765` as the Homepage URL.
+4. Set `http://localhost:8765/callback` as the Authorized Redirect URI.
+5. Click the Create button.
+6. Copy the client ID and client secret from the Client Secret tab.
+7. Save them in your shell configuration file (`~/.bashrc` or `~/.zshrc`):
+
+   ```sh
+   export ZOHO_CLIENT_ID="..."
+   export ZOHO_CLIENT_SECRET="..."
    ```
 
-6. Copy the client ID and client secret. Use them as `ZOHO_CLIENT_ID` and `ZOHO_CLIENT_SECRET`.
-
 zsync opens a local callback on port 8765 during the first authorization. The redirect URI must match exactly, including the scheme, port, and path.
 
 ## Request the required scopes
@@ -23,19 +24,15 @@ zsync opens a local callback on port 8765 during the first authorization. The re
 zsync requests these scopes during authorization:
 
 ```text
-ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.forms.READ,AaaServer.profile.READ
+ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.forms.READ,ZOHOPEOPLE.forms.CREATE,AaaServer.profile.READ
 ```
 
-`ZOHOPEOPLE.timetracker.ALL` lets zsync read and change time logs and list assigned jobs. The forms and profile scopes let it find your employee record from your email address.
+`ZOHOPEOPLE.timetracker.ALL` lets zsync read and change time logs and list assigned projects and jobs. `ZOHOPEOPLE.forms.CREATE` lets it create missing tag jobs under the selected project. The `ZOHOPEOPLE.forms.READ` and `AaaServer.profile.READ` scopes let it find your employee record from your email address.
 
 See Zoho's [OAuth scopes](https://www.zoho.com/people/api/scopes.html) page for scope details.
 
 ## Check your Zoho access
 
-Your Zoho People role must allow Time Tracker API access. Your employee record must have an eligible, assigned job. Ask your People administrator if zsync reports that no jobs are available.
+Your Zoho People role must allow Time Tracker API access. Your employee record must have an eligible, assigned project and permission to create and assign jobs. Ask your People administrator if zsync reports that no projects are available or job creation is denied.
 
 If zsync cannot find your employee record by email, it asks for the numeric `ERECNO`. This is the employee record ID. It is different from the employee number shown in the People interface. You can also set it with `ZOHO_EMPLOYEE_ID`.
-
-## Keep credentials safe
-
-Do not commit the client ID, client secret, or refresh token to a repository. zsync saves the Zoho refresh token locally after authorization. It does not save the client secret.

package/package.json

@@ -1,43 +1,43 @@
 {
-  "name": "@srafis/zsync",
-  "type": "module",
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^22.20.2",
-    "typescript": "^7.0.2"
-  },
-  "dependencies": {
-    "@clack/core": "1.5.0",
-    "@clack/prompts": "^1.8.0",
-    "@js-temporal/polyfill": "^0.5.1",
-    "fast-string-width": "3.0.2"
-  },
-  "version": "0.1.6",
-  "description": "Interactively sync Clockify entries to Zoho People",
-  "bin": {
-    "zsync": "dist/zsync.js"
-  },
-  "files": [
-    "dist/zsync.js",
-    "README.md",
-    "docs"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "dev": "bun app.ts",
-    "build": "bun build app.ts --target=node --outfile=dist/zsync.js",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "prepack": "bun run build"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/srafis/zoho-clockify-sync.git"
-  }
+	"name": "@srafis/zsync",
+	"type": "module",
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/node": "^22.20.2",
+		"typescript": "^7.0.2"
+	},
+	"dependencies": {
+		"@clack/core": "1.5.0",
+		"@clack/prompts": "^1.8.0",
+		"@js-temporal/polyfill": "^0.5.1",
+		"fast-string-width": "3.0.2"
+	},
+	"version": "0.1.8",
+	"description": "Interactively sync Clockify entries to Zoho People",
+	"bin": {
+		"zsync": "dist/zsync.js"
+	},
+	"files": [
+		"dist/zsync.js",
+		"README.md",
+		"docs"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"scripts": {
+		"dev": "bun app.ts",
+		"build": "bun build app.ts --target=node --outfile=dist/zsync.js",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"prepack": "bun run build"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/srafis/zoho-clockify-sync.git"
+	}
 }