@platforma-sdk/pl-cli 0.2.0

package/src/cmd/project/duplicate.ts

@@ -0,0 +1,80 @@
+import { Args, Flags } from "@oclif/core";
+import { field, toGlobalResourceId } from "@milaboratories/pl-client";
+import { ProjectMetaKey } from "@milaboratories/pl-middle-layer";
+import { randomUUID } from "node:crypto";
+import { PlCommand } from "../../base_command";
+import {
+  resolveProject,
+  deduplicateName,
+  duplicateProject,
+  getExistingLabelsInTx,
+} from "../../project_ops";
+import { outputJson, outputText } from "../../output";
+
+export default class ProjectDuplicate extends PlCommand {
+  static override description =
+    "Duplicate a project within the same user. Auto-renames on collision by default.";
+
+  static override args = {
+    project: Args.string({
+      description: "Project ID or label",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...PlCommand.baseFlags,
+    name: Flags.string({
+      char: "n",
+      summary: "Name for the duplicate",
+      helpValue: "<name>",
+    }),
+    "auto-rename": Flags.boolean({
+      summary: "Auto-rename on collision (default: true)",
+      default: true,
+      allowNo: true,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(ProjectDuplicate);
+    const { pl, projectListRid } = await this.connect(flags);
+
+    const { rid: sourceRid } = await resolveProject(pl, projectListRid, args.project);
+
+    const newId = randomUUID();
+
+    const newRid = await pl.withWriteTx("duplicateProject", async (tx) => {
+      const sourceMetaStr = await tx.getKValueString(sourceRid, ProjectMetaKey);
+      const sourceMeta = JSON.parse(sourceMetaStr);
+      const sourceLabel: string = sourceMeta.label;
+
+      const existingLabels = await getExistingLabelsInTx(tx, projectListRid);
+
+      // Compute new label
+      let newLabel: string;
+      if (flags.name) {
+        if (!flags["auto-rename"] && existingLabels.includes(flags.name)) {
+          throw new Error(`Project name "${flags.name}" already exists.`);
+        }
+        newLabel = existingLabels.includes(flags.name)
+          ? deduplicateName(flags.name, existingLabels)
+          : flags.name;
+      } else {
+        newLabel = deduplicateName(sourceLabel, existingLabels);
+      }
+
+      const newPrj = await duplicateProject(tx, sourceRid, { label: newLabel });
+      tx.createField(field(projectListRid, newId), "Dynamic", newPrj);
+      await tx.commit();
+
+      return { rid: await toGlobalResourceId(newPrj), label: newLabel };
+    });
+
+    if (flags.format === "json") {
+      outputJson({ id: newId, rid: String(newRid.rid), label: newRid.label });
+    } else {
+      outputText(`Duplicated project as "${newRid.label}" (id: ${newId})`);
+    }
+  }
+}

package/src/cmd/project/info.ts

@@ -0,0 +1,52 @@
+import { Args } from "@oclif/core";
+import { PlCommand } from "../../base_command";
+import { resolveProject, getProjectInfo } from "../../project_ops";
+import { formatDate, outputJson, outputText } from "../../output";
+
+export default class ProjectInfo extends PlCommand {
+  static override description = "Show detailed information about a project.";
+
+  static override args = {
+    project: Args.string({
+      description: "Project ID or label",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...PlCommand.baseFlags,
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(ProjectInfo);
+    const { pl, projectListRid } = await this.connect(flags);
+    const { id } = await resolveProject(pl, projectListRid, args.project);
+    const info = await getProjectInfo(pl, projectListRid, id);
+
+    if (flags.format === "json") {
+      outputJson({
+        id: info.id,
+        rid: info.rid,
+        label: info.label,
+        schemaVersion: info.schemaVersion,
+        blockCount: info.blockCount,
+        blockIds: info.blockIds,
+        created: info.created.toISOString(),
+        lastModified: info.lastModified.toISOString(),
+      });
+    } else {
+      outputText(`Project: ${info.label}`);
+      outputText(`ID:      ${info.id}`);
+      outputText(`RID:     ${info.rid}`);
+      outputText(`Schema:  ${info.schemaVersion ?? "(unknown)"}`);
+      outputText(`Blocks:  ${info.blockCount}`);
+      if (info.blockIds.length > 0) {
+        for (const bid of info.blockIds) {
+          outputText(`  - ${bid}`);
+        }
+      }
+      outputText(`Created:       ${formatDate(info.created)}`);
+      outputText(`Last Modified: ${formatDate(info.lastModified)}`);
+    }
+  }
+}

package/src/cmd/project/list.ts

@@ -0,0 +1,47 @@
+import { PlCommand } from "../../base_command";
+import { listProjects } from "../../project_ops";
+import { formatTable, formatDate, outputJson, outputText } from "../../output";
+
+export default class ProjectList extends PlCommand {
+  static override description = "List all projects for the authenticated user.";
+
+  static override flags = {
+    ...PlCommand.baseFlags,
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(ProjectList);
+    const { pl, projectListRid } = await this.connect(flags);
+    const projects = await listProjects(pl, projectListRid);
+
+    if (flags.format === "json") {
+      outputJson(
+        projects.map((p) => ({
+          id: p.id,
+          rid: p.rid,
+          label: p.label,
+          created: p.created.toISOString(),
+          lastModified: p.lastModified.toISOString(),
+        })),
+      );
+    } else {
+      if (projects.length === 0) {
+        outputText("No projects found.");
+        return;
+      }
+
+      outputText(
+        formatTable(
+          ["ID", "LABEL", "CREATED", "LAST MODIFIED"],
+          projects.map((p) => [
+            p.id.substring(0, 8) + "...",
+            p.label,
+            formatDate(p.created),
+            formatDate(p.lastModified),
+          ]),
+        ),
+      );
+      outputText(`\n${projects.length} project(s)`);
+    }
+  }
+}

package/src/cmd/project/rename.ts

@@ -0,0 +1,39 @@
+import { Args, Flags } from "@oclif/core";
+import { PlCommand } from "../../base_command";
+import { resolveProject, renameProject } from "../../project_ops";
+import { outputJson, outputText } from "../../output";
+
+export default class ProjectRename extends PlCommand {
+  static override description = "Rename a project.";
+
+  static override args = {
+    project: Args.string({
+      description: "Project ID or label",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...PlCommand.baseFlags,
+    name: Flags.string({
+      char: "n",
+      summary: "New name for the project",
+      helpValue: "<name>",
+      required: true,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(ProjectRename);
+    const { pl, projectListRid } = await this.connect(flags);
+    const { id, rid } = await resolveProject(pl, projectListRid, args.project);
+
+    await renameProject(pl, rid, flags.name);
+
+    if (flags.format === "json") {
+      outputJson({ id, rid: String(rid), label: flags.name });
+    } else {
+      outputText(`Renamed project to "${flags.name}"`);
+    }
+  }
+}

package/src/cmd-opts.ts

@@ -0,0 +1,60 @@
+import { Flags } from "@oclif/core";
+
+export const GlobalFlags = {
+  address: Flags.string({
+    char: "a",
+    summary: "Platforma server address",
+    helpValue: "<url>",
+    env: "PL_ADDRESS",
+    required: true,
+  }),
+  format: Flags.string({
+    char: "f",
+    summary: "Output format",
+    options: ["text", "json"],
+    default: "text",
+  }),
+};
+
+export const UserAuthFlags = {
+  user: Flags.string({
+    char: "u",
+    summary: "Username for authentication",
+    env: "PL_USER",
+  }),
+  password: Flags.string({
+    char: "p",
+    summary: "Password for authentication",
+    env: "PL_PASSWORD",
+  }),
+};
+
+/** Admin credentials only (for purely admin commands like copy-project). */
+export const AdminAuthFlags = {
+  "admin-user": Flags.string({
+    summary: "Admin/controller username",
+    env: "PL_ADMIN_USER",
+    required: true,
+  }),
+  "admin-password": Flags.string({
+    summary: "Admin/controller password",
+    env: "PL_ADMIN_PASSWORD",
+    required: true,
+  }),
+};
+
+/** Admin credentials + target user (for regular commands that can optionally operate on another user). */
+export const AdminTargetFlags = {
+  "admin-user": Flags.string({
+    summary: "Admin/controller username (enables admin mode)",
+    env: "PL_ADMIN_USER",
+  }),
+  "admin-password": Flags.string({
+    summary: "Admin/controller password",
+    env: "PL_ADMIN_PASSWORD",
+  }),
+  "target-user": Flags.string({
+    summary: "Operate on this user's data (requires admin credentials)",
+    env: "PL_TARGET_USER",
+  }),
+};

package/src/connection.ts

@@ -0,0 +1,54 @@
+import {
+  PlClient,
+  UnauthenticatedPlClient,
+  plAddressToConfig,
+  type AuthInformation,
+  type PlClientConfig,
+} from "@milaboratories/pl-client";
+
+export interface PlConnectionOptions {
+  address: string;
+  user?: string;
+  password?: string;
+}
+
+export interface AdminConnectionOptions {
+  address: string;
+  adminUser: string;
+  adminPassword: string;
+}
+
+/** Creates an authenticated PlClient from address + credentials. */
+export async function createPlConnection(opts: PlConnectionOptions): Promise<PlClient> {
+  const config: PlClientConfig = plAddressToConfig(opts.address);
+
+  if (opts.user !== undefined) config.user = opts.user;
+  if (opts.password !== undefined) config.password = opts.password;
+
+  const unauth = await UnauthenticatedPlClient.build(config);
+  let authInformation: AuthInformation;
+
+  if (await unauth.requireAuth()) {
+    if (config.user === undefined || config.password === undefined) {
+      throw new Error(
+        "Server requires authentication but no credentials provided. " +
+          "Use --user/--password flags or PL_USER/PL_PASSWORD env vars.",
+      );
+    }
+    authInformation = await unauth.login(config.user, config.password);
+  } else {
+    authInformation = {};
+  }
+
+  return await PlClient.init(config, { authInformation });
+}
+
+/** Creates a PlClient with admin/controller credentials. */
+export async function createAdminPlConnection(opts: AdminConnectionOptions): Promise<PlClient> {
+  const config: PlClientConfig = plAddressToConfig(opts.address);
+
+  const unauth = await UnauthenticatedPlClient.build(config);
+  const authInformation: AuthInformation = await unauth.login(opts.adminUser, opts.adminPassword);
+
+  return await PlClient.init(config, { authInformation });
+}

package/src/lib.ts

@@ -0,0 +1,21 @@
+export {
+  createPlConnection,
+  createAdminPlConnection,
+  type PlConnectionOptions,
+  type AdminConnectionOptions,
+} from "./connection";
+export {
+  listProjects,
+  getProjectInfo,
+  getProjectListRid,
+  getExistingLabelsInTx,
+  resolveProject,
+  renameProject,
+  deleteProject,
+  deduplicateName,
+  navigateToUserRoot,
+  duplicateProject,
+  type ProjectEntry,
+  type ProjectInfo,
+} from "./project_ops";
+export { type OutputFormat, outputText, outputJson, formatTable, formatDate } from "./output";

package/src/output.ts

@@ -0,0 +1,35 @@
+export type OutputFormat = "text" | "json";
+
+/** Outputs a line of text to stdout. */
+export function outputText(message: string): void {
+  console.log(message);
+}
+
+/** Outputs data as formatted JSON to stdout. */
+export function outputJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/** Formats a table as aligned text columns. */
+export function formatTable(headers: string[], rows: string[][]): string {
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)),
+  );
+
+  const sep = colWidths.map((w) => "-".repeat(w)).join("  ");
+  const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join("  ");
+  const dataLines = rows.map((row) =>
+    row.map((cell, i) => (cell ?? "").padEnd(colWidths[i])).join("  "),
+  );
+
+  return [headerLine, sep, ...dataLines].join("\n");
+}
+
+/** Formats a Date as a short human-readable string. */
+export function formatDate(d: Date): string {
+  if (d.getTime() === 0) return "(unknown)";
+  return d
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d+Z$/, "Z");
+}

package/src/project_ops.ts

@@ -0,0 +1,251 @@
+import type { PlClient, ResourceId, PlTransaction } from "@milaboratories/pl-client";
+import { field, isNullResourceId } from "@milaboratories/pl-client";
+import {
+  ProjectMetaKey,
+  ProjectCreatedTimestamp,
+  ProjectLastModifiedTimestamp,
+  SchemaVersionKey,
+  ProjectStructureKey,
+  ProjectsField,
+  duplicateProject,
+} from "@milaboratories/pl-middle-layer";
+import type { ProjectMeta } from "@milaboratories/pl-middle-layer";
+import { createHash } from "node:crypto";
+
+export interface ProjectEntry {
+  id: string;
+  rid: string;
+  label: string;
+  created: Date;
+  lastModified: Date;
+}
+
+export interface ProjectInfo extends ProjectEntry {
+  schemaVersion: string | undefined;
+  blockCount: number;
+  blockIds: string[];
+}
+
+/** List all projects from a project list resource. */
+export async function listProjects(
+  pl: PlClient,
+  projectListRid: ResourceId,
+): Promise<ProjectEntry[]> {
+  return await pl.withReadTx("listProjects", async (tx) => {
+    const data = await tx.getResourceData(projectListRid, true);
+    const entries: ProjectEntry[] = [];
+
+    for (const f of data.fields) {
+      if (isNullResourceId(f.value)) continue;
+
+      const [metaStr, createdStr, modifiedStr] = await Promise.all([
+        tx.getKValueStringIfExists(f.value, ProjectMetaKey),
+        tx.getKValueStringIfExists(f.value, ProjectCreatedTimestamp),
+        tx.getKValueStringIfExists(f.value, ProjectLastModifiedTimestamp),
+      ]);
+
+      const meta: ProjectMeta = metaStr ? JSON.parse(metaStr) : { label: "(unknown)" };
+
+      entries.push({
+        id: f.name,
+        rid: String(f.value),
+        label: meta.label,
+        created: createdStr ? new Date(Number(createdStr)) : new Date(0),
+        lastModified: modifiedStr ? new Date(Number(modifiedStr)) : new Date(0),
+      });
+    }
+
+    entries.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+    return entries;
+  });
+}
+
+/** Get detailed info about a project. */
+export async function getProjectInfo(
+  pl: PlClient,
+  projectListRid: ResourceId,
+  projectId: string,
+): Promise<ProjectInfo> {
+  return await pl.withReadTx("getProjectInfo", async (tx) => {
+    const fieldData = await tx.getField(field(projectListRid, projectId));
+    if (isNullResourceId(fieldData.value)) {
+      throw new Error(`Project "${projectId}" not found.`);
+    }
+
+    const rid = fieldData.value;
+    const kvs = await tx.listKeyValuesString(rid);
+
+    const metaKV = kvs.find((kv: { key: string }) => kv.key === ProjectMetaKey);
+    const createdKV = kvs.find((kv: { key: string }) => kv.key === ProjectCreatedTimestamp);
+    const modifiedKV = kvs.find((kv: { key: string }) => kv.key === ProjectLastModifiedTimestamp);
+    const schemaKV = kvs.find((kv: { key: string }) => kv.key === SchemaVersionKey);
+    const structureKV = kvs.find((kv: { key: string }) => kv.key === ProjectStructureKey);
+
+    const meta: ProjectMeta = metaKV ? JSON.parse(metaKV.value) : { label: "(unknown)" };
+    const schemaVersion = schemaKV ? JSON.parse(schemaKV.value) : undefined;
+
+    const blockIds: string[] = [];
+    if (structureKV) {
+      const structure = JSON.parse(structureKV.value);
+      for (const group of structure.groups ?? []) {
+        for (const block of group.blocks ?? []) {
+          blockIds.push(block.id);
+        }
+      }
+    }
+
+    return {
+      id: projectId,
+      rid: String(rid),
+      label: meta.label,
+      created: createdKV ? new Date(Number(createdKV.value)) : new Date(0),
+      lastModified: modifiedKV ? new Date(Number(modifiedKV.value)) : new Date(0),
+      schemaVersion,
+      blockCount: blockIds.length,
+      blockIds,
+    };
+  });
+}
+
+/** Resolve a project identifier (id or label) to its field ID and ResourceId. */
+export async function resolveProject(
+  pl: PlClient,
+  projectListRid: ResourceId,
+  identifier: string,
+): Promise<{ id: string; rid: ResourceId }> {
+  return await pl.withReadTx("resolveProject", async (tx) => {
+    const data = await tx.getResourceData(projectListRid, true);
+    for (const f of data.fields) {
+      if (isNullResourceId(f.value)) continue;
+      if (f.name === identifier) {
+        return { id: f.name, rid: f.value };
+      }
+      const metaStr = await tx.getKValueStringIfExists(f.value, ProjectMetaKey);
+      if (metaStr) {
+        const meta: ProjectMeta = JSON.parse(metaStr);
+        if (meta.label === identifier) {
+          return { id: f.name, rid: f.value };
+        }
+      }
+    }
+
+    throw new Error(`Project "${identifier}" not found (searched by id and label).`);
+  });
+}
+
+/** Read all project labels within an existing transaction. */
+export async function getExistingLabelsInTx(
+  tx: PlTransaction,
+  projectListRid: ResourceId,
+): Promise<string[]> {
+  const data = await tx.getResourceData(projectListRid, true);
+  const labels: string[] = [];
+  for (const f of data.fields) {
+    if (isNullResourceId(f.value)) continue;
+    const metaStr = await tx.getKValueStringIfExists(f.value, ProjectMetaKey);
+    if (metaStr) {
+      const meta: ProjectMeta = JSON.parse(metaStr);
+      labels.push(meta.label);
+    }
+  }
+  return labels;
+}
+
+/** Get all project labels from a project list. */
+export async function getProjectLabels(
+  pl: PlClient,
+  projectListRid: ResourceId,
+): Promise<string[]> {
+  return await pl.withReadTx("getProjectLabels", async (tx) => {
+    return getExistingLabelsInTx(tx, projectListRid);
+  });
+}
+
+/**
+ * Deduplicates a project name against existing labels.
+ * "X" → "X (Copy)" → "X (Copy 2)" → ...
+ */
+export function deduplicateName(baseName: string, existingLabels: string[]): string {
+  let candidate = `${baseName} (Copy)`;
+  let i = 2;
+  while (existingLabels.includes(candidate)) {
+    candidate = `${baseName} (Copy ${i})`;
+    i++;
+  }
+  return candidate;
+}
+
+/** Rename a project (update its label). */
+export async function renameProject(
+  pl: PlClient,
+  projectRid: ResourceId,
+  newLabel: string,
+): Promise<void> {
+  await pl.withWriteTx("renameProject", async (tx) => {
+    const metaStr = await tx.getKValueString(projectRid, ProjectMetaKey);
+    const meta: ProjectMeta = JSON.parse(metaStr);
+    const updated: ProjectMeta = { ...meta, label: newLabel };
+    tx.setKValue(projectRid, ProjectMetaKey, JSON.stringify(updated));
+    tx.setKValue(projectRid, ProjectLastModifiedTimestamp, String(Date.now()));
+    await tx.commit();
+  });
+}
+
+/** Delete a project from the project list. */
+export async function deleteProject(
+  pl: PlClient,
+  projectListRid: ResourceId,
+  projectId: string,
+): Promise<void> {
+  await pl.withWriteTx("deleteProject", async (tx) => {
+    tx.removeField(field(projectListRid, projectId));
+    await tx.commit();
+  });
+}
+
+/** Get the project list ResourceId for the connected user. */
+export async function getProjectListRid(pl: PlClient): Promise<ResourceId> {
+  return await pl.withReadTx("getProjectList", async (tx) => {
+    const fieldData = await tx.getField({
+      resourceId: tx.clientRoot,
+      fieldName: ProjectsField,
+    });
+    if (isNullResourceId(fieldData.value)) {
+      throw new Error("No project list found for this user.");
+    }
+    return fieldData.value;
+  });
+}
+
+/**
+ * Navigates to a specific user's project list resource ID.
+ * Computes SHA256(username) to find the user's root, then reads the "projects" field.
+ */
+export async function navigateToUserRoot(
+  pl: PlClient,
+  username: string,
+): Promise<{ userRoot: ResourceId; projectListRid: ResourceId }> {
+  const rootName = createHash("sha256").update(username).digest("hex");
+
+  return await pl.withReadTx("navigateToUserRoot", async (tx) => {
+    if (!(await tx.checkResourceNameExists(rootName))) {
+      throw new Error(`User "${username}" not found on this server (no root resource).`);
+    }
+
+    const userRootRid = await tx.getResourceByName(rootName);
+
+    const projectsFieldData = await tx.getField({
+      resourceId: userRootRid,
+      fieldName: ProjectsField,
+    });
+
+    if (isNullResourceId(projectsFieldData.value)) {
+      throw new Error(`User "${username}" has no project list.`);
+    }
+
+    return { userRoot: userRootRid, projectListRid: projectsFieldData.value };
+  });
+}
+
+// Re-export duplicateProject from pl-middle-layer for use in commands
+export { duplicateProject };