sv

Author: nighca

spx-gui/AGENTS.md

@@ -35,6 +35,28 @@ Keep import statements in order:
 	- Enum names and enum members
 	- Vue component names
 
+### Identifier Resolution
+
+When working with backend unique string identifiers such as `username`, project owner, and project name, distinguish unresolved identifiers from canonical identifiers.
+
+* Treat values from route params, query params, and manual user input as unresolved identifiers.
+
+* Treat backend-issued values as canonical identifiers, including:
+	- HTTP API responses
+	- JWT token fields such as `username`
+
+* Prefer naming unresolved values explicitly, such as `ownerInput`, `projectNameInput`, or similar names that make the unresolved nature obvious.
+
+* In models and resolved state, names like `owner`, `name`, and `username` should refer to canonical values.
+
+* Keep normal strict and case-sensitive equality (`===` / `!==`) for consuming identifiers. Do not spread ad hoc case-normalization logic across comparison sites.
+
+* Resolve unresolved identifiers at clear boundaries before consuming them. Typical resolution boundaries include project loading, user loading, and other backend-backed fetches.
+
+* Avoid storing unresolved identifiers on long-lived models as if they were already canonical. Prefer passing unresolved identifiers as load or resolve parameters, then writing canonical values onto the model after resolution.
+
+* Downstream logic should consume canonical values only. This includes ownership checks, permission checks, cache keys, project reuse checks, local-cache decisions, and similar logic.
+
 ## TypeScript Testing
 
 * Use `describe` to group related tests.

spx-gui/src/components/common/ListResultWrapper.vue

@@ -13,7 +13,7 @@ import { UILoading, UIError, UIEmpty } from '@/components/ui'
 import type { ByPage } from '@/apis/common'
 
 const props = defineProps<{
-  queryRet: QueryRet<T>
+  queryRet: QueryRet<T | null>
   height?: number
   /** Type of the list content */
   contentType?: 'project'

spx-gui/src/components/community/ProjectsSection.vue

@@ -46,7 +46,7 @@ type Context = 'home' | 'user' | 'project'
 
 defineProps<{
   linkTo?: string | null
-  queryRet: QueryRet<unknown[]>
+  queryRet: QueryRet<unknown[] | null>
   context: Context
   numInRow: number
 }>()

spx-gui/src/components/community/project/ReleaseHistory.vue

@@ -6,7 +6,7 @@ import { UITimeline, UITimelineItem, UILoading, UIError } from '@/components/ui'
 import TextView from '../TextView.vue'
 
 defineProps<{
-  queryRet: QueryRet<ProjectRelease[]>
+  queryRet: QueryRet<ProjectRelease[] | null>
 }>()
 </script>
 

spx-gui/src/components/copilot/CopilotRoot.vue

@@ -58,17 +58,25 @@ class Retriever {
     private cloudHelpers: CloudHelpers
   ) {}
 
+  private matchesIdentifierInput(canonical: string | null | undefined, input: string | null | undefined) {
+    return canonical != null && input != null && canonical.toLowerCase() === input.toLowerCase()
+  }
+
   async getProject(project: string | undefined, signal?: AbortSignal): Promise<SpxProject> {
     const currentProject = this.editorCtxRef.value?.project
     if (project == null) {
       if (currentProject == null) throw new Error('No project specified and no current editing project available')
       return currentProject
     }
     const { owner, name } = parseProjectIdentifier(project)
-    if (currentProject != null && currentProject.owner === owner && currentProject.name === name) {
+    if (
+      currentProject != null &&
+      this.matchesIdentifierInput(currentProject.owner, owner) &&
+      this.matchesIdentifierInput(currentProject.name, name)
+    ) {
       return currentProject
     }
-    const p = new SpxProject(owner, name)
+    const p = new SpxProject()
     const serialized = await this.cloudHelpers.load(owner, name, true, signal)
     await p.load(serialized)
     return p

spx-gui/src/components/editor/editing.test.ts

@@ -8,7 +8,7 @@ import { type Files } from '@/models/common/file'
 import type { CloudHelpers } from '@/models/common/cloud'
 import { mockFile, MockProject } from '@/models/common/test'
 import type { IProject, ProjectSerialized } from '@/models/project'
-import { Editing, SavingState, EditingMode, type ILocalCache, type UIHelpersForLoadingProject } from './editing'
+import { Editing, SavingState, EditingMode, type ILocalCache, type LoadProjectParams, type UIHelpersForLoadingProject } from './editing'
 
 function makeFiles() {
   return {
@@ -284,6 +284,10 @@ describe('Editing.loadProject', () => {
     }
   }
 
+  function makeLoadProjectParams(ownerInput = 'alice', projectNameInput = 'my-project'): LoadProjectParams {
+    return { ownerInput, projectNameInput }
+  }
+
   function makeSerialized(owner: string, name: string, version?: number): ProjectSerialized {
     return {
       metadata: { owner, name, version },
@@ -301,7 +305,7 @@ describe('Editing.loadProject', () => {
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
     const ac = new AbortController()
-    await editing.loadProject(makeUIHelpers(), makeReporter(), ac.signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), ac.signal)
 
     expect(cloudHelper.load).toHaveBeenCalledWith('alice', 'my-project', false, ac.signal)
     expect(project.load).toHaveBeenCalledWith(cloudData, ac.signal)
@@ -318,7 +322,7 @@ describe('Editing.loadProject', () => {
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
     const ac = new AbortController()
-    await editing.loadProject(makeUIHelpers(), makeReporter(), ac.signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), ac.signal)
 
     expect(cloudHelper.load).toHaveBeenCalledWith('alice', 'my-project', false, ac.signal)
     expect(project.load).toHaveBeenCalledWith(cloudData, ac.signal)
@@ -335,7 +339,7 @@ describe('Editing.loadProject', () => {
     const project = makeProject({ owner: 'alice', name: 'my-project' })
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
-    await editing.loadProject(makeUIHelpers(), makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), new AbortController().signal)
 
     expect(project.load).toHaveBeenCalledWith(localData, expect.anything())
   })
@@ -350,7 +354,7 @@ describe('Editing.loadProject', () => {
     const project = makeProject({ owner: 'alice', name: 'my-project' })
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
-    await editing.loadProject(makeUIHelpers(), makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), new AbortController().signal)
 
     expect(project.load).toHaveBeenCalledWith(cloudData, expect.anything())
     expect(localCacheHelper.clear).toHaveBeenCalled()
@@ -366,7 +370,7 @@ describe('Editing.loadProject', () => {
     const project = makeProject({ owner: 'alice', name: 'my-project' })
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
-    await editing.loadProject(makeUIHelpers(), makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), new AbortController().signal)
 
     expect(localCacheHelper.clear).toHaveBeenCalled()
     expect(project.load).toHaveBeenCalledWith(cloudData, expect.anything())
@@ -385,7 +389,7 @@ describe('Editing.loadProject', () => {
     const helpers = makeUIHelpers()
     vi.mocked(helpers.confirmOpenTargetWithAnotherInCache).mockResolvedValue(true)
 
-    await editing.loadProject(helpers, makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), helpers, makeReporter(), new AbortController().signal)
 
     expect(helpers.confirmOpenTargetWithAnotherInCache).toHaveBeenCalledWith('my-project', 'other-project')
     expect(localCacheHelper.clear).toHaveBeenCalled()
@@ -404,7 +408,7 @@ describe('Editing.loadProject', () => {
 
     const helpers = makeUIHelpers()
 
-    await editing.loadProject(helpers, makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), helpers, makeReporter(), new AbortController().signal)
 
     expect(helpers.confirmOpenTargetWithAnotherInCache).not.toHaveBeenCalled()
     expect(localCacheHelper.clear).not.toHaveBeenCalled()
@@ -424,19 +428,23 @@ describe('Editing.loadProject', () => {
     const helpers = makeUIHelpers()
     vi.mocked(helpers.confirmOpenTargetWithAnotherInCache).mockResolvedValue(false)
 
-    await expect(editing.loadProject(helpers, makeReporter(), new AbortController().signal)).rejects.toThrow(Cancelled)
+    await expect(editing.loadProject(makeLoadProjectParams(), helpers, makeReporter(), new AbortController().signal)).rejects.toThrow(Cancelled)
     expect(localCacheHelper.clear).not.toHaveBeenCalled()
     expect(helpers.openProject).toHaveBeenCalledWith('alice', 'cached-project')
     expect(project.load).not.toHaveBeenCalled()
   })
 
-  it('should throw when project has no owner or name', async () => {
+  it('should load project when the model starts without owner or name', async () => {
+    const cloudData = makeSerialized('alice', 'my-project', 1)
+    const cloudHelper = makeCloudHelper()
+    vi.mocked(cloudHelper.load).mockResolvedValue(cloudData)
     const project = new MockProject(undefined, undefined, makeFiles())
-    const editing = makeEditing({ project })
+    const editing = makeEditing({ project, cloudHelper, signedInUsername: 'alice' })
 
-    await expect(editing.loadProject(makeUIHelpers(), makeReporter(), new AbortController().signal)).rejects.toThrow(
-      'Project owner and name expected'
-    )
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), new AbortController().signal)
+
+    expect(project.load).toHaveBeenCalledWith(cloudData, expect.anything())
+    expect(editing.mode).toBe(EditingMode.AutoSave)
   })
 
   it('should set preferPublishedContent to false when signed-in user is the owner', async () => {
@@ -449,7 +457,7 @@ describe('Editing.loadProject', () => {
     const editing = new Editing(project, cloudHelper, localCacheHelper, () => true, 'alice')
 
     const ac = new AbortController()
-    await editing.loadProject(makeUIHelpers(), makeReporter(), ac.signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), ac.signal)
 
     expect(cloudHelper.load).toHaveBeenCalledWith('alice', 'my-project', false, ac.signal)
   })
@@ -464,11 +472,30 @@ describe('Editing.loadProject', () => {
     const editing = new Editing(project, cloudHelper, localCacheHelper, () => true, 'bob')
 
     const ac = new AbortController()
-    await editing.loadProject(makeUIHelpers(), makeReporter(), ac.signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), ac.signal)
 
     expect(cloudHelper.load).toHaveBeenCalledWith('alice', 'my-project', true, ac.signal)
   })
 
+  it('should treat owner input with different casing as the same owner', async () => {
+    const cloudData = makeSerialized('alice', 'my-project', 1)
+    const localData = makeSerialized('alice', 'my-project', 2)
+    const cloudHelper = makeCloudHelper()
+    vi.mocked(cloudHelper.load).mockResolvedValue(cloudData)
+    const localCacheHelper = makeLocalCache(localData)
+
+    const project = new MockProject(undefined, undefined, makeFiles())
+    const editing = makeEditing({ project, cloudHelper, localCacheHelper, signedInUsername: 'alice' })
+
+    const ac = new AbortController()
+    await editing.loadProject(makeLoadProjectParams('Alice', 'my-project'), makeUIHelpers(), makeReporter(), ac.signal)
+
+    expect(cloudHelper.load).toHaveBeenCalledWith('Alice', 'my-project', false, ac.signal)
+    expect(localCacheHelper.clear).not.toHaveBeenCalled()
+    expect(project.load).toHaveBeenCalledWith(localData, expect.anything())
+    expect(editing.mode).toBe(EditingMode.AutoSave)
+  })
+
   it('should prefer local cache when cloud version is undefined and local version is undefined', async () => {
     const cloudData = makeSerialized('alice', 'my-project')
     const localData = makeSerialized('alice', 'my-project')
@@ -479,7 +506,7 @@ describe('Editing.loadProject', () => {
     const project = makeProject({ owner: 'alice', name: 'my-project' })
     const editing = makeEditing({ project, cloudHelper, localCacheHelper })
 
-    await editing.loadProject(makeUIHelpers(), makeReporter(), new AbortController().signal)
+    await editing.loadProject(makeLoadProjectParams(), makeUIHelpers(), makeReporter(), new AbortController().signal)
 
     // Both versions are undefined (-1 == -1), so cloudVersion > localVersion is false, local data wins
     expect(project.load).toHaveBeenCalledWith(localData, expect.anything())

spx-gui/src/components/editor/editing.ts

@@ -95,6 +95,15 @@ export type UIHelpersForLoadingProject = {
   openProject: (owner: string, name: string) => void
 }
 
+export type LoadProjectParams = {
+  ownerInput: string
+  projectNameInput: string
+}
+
+function matchesIdentifierInput(canonical: string | null | undefined, input: string | null | undefined) {
+  return canonical != null && input != null && canonical.toLowerCase() === input.toLowerCase()
+}
+
 /**
  * `Editing` manages the lifecycle of editing a project, including:
  * - Determining the editing mode (AutoSave vs EffectFree) based on user ownership
@@ -110,7 +119,7 @@ export type UIHelpersForLoadingProject = {
  * renaming it with a more accurate name.
  */
 export class Editing extends Disposable {
-  mode: EditingMode
+  mode = EditingMode.AutoSave
   constructor(
     private project: IProject,
     private cloudHelpers: CloudHelpers,
@@ -119,8 +128,13 @@ export class Editing extends Disposable {
     private signedInUsername: string | null
   ) {
     super()
+    this.updateMode()
+  }
+
+  private updateMode() {
+    const owner = this.project.owner
     this.mode = EditingMode.AutoSave
-    if (signedInUsername == null || signedInUsername !== this.project.owner) {
+    if (this.signedInUsername == null || owner == null || this.signedInUsername !== owner) {
       this.mode = EditingMode.EffectFree
     }
   }
@@ -188,7 +202,12 @@ export class Editing extends Disposable {
     )
   }
 
-  async loadProject(helpers: UIHelpersForLoadingProject, reporter: ProgressReporter, signal: AbortSignal) {
+  async loadProject(
+    { ownerInput, projectNameInput }: LoadProjectParams,
+    helpers: UIHelpersForLoadingProject,
+    reporter: ProgressReporter,
+    signal: AbortSignal
+  ) {
     const collector = ProgressCollector.collectorFor(reporter)
     const loadFromLocalCacheReporter = collector.getSubReporter(
       { en: 'Reading local cache...', zh: '读取本地缓存中...' },
@@ -200,9 +219,6 @@ export class Editing extends Disposable {
     )
     const projectLoadReporter = collector.getSubReporter({ en: 'Loading project...', zh: '加载项目中...' }, 5)
 
-    const { owner: ownerName, name: projectName } = this.project
-    if (ownerName == null || projectName == null) throw new Error('Project owner and name expected')
-
     // For details about local-cache saving & restoring
     // https://github.com/goplus/builder/issues/259
     // https://github.com/goplus/builder/issues/393
@@ -217,22 +233,23 @@ export class Editing extends Disposable {
     if (localData != null) {
       const localMetadata = localData.metadata
       // If owner mismatch, ignore & clear the cached data
-      if (localMetadata.owner !== ownerName) {
+      if (!matchesIdentifierInput(localMetadata.owner, ownerInput)) {
         localData = null
         this.localCacheHelper.clear().catch((e) => capture(e, 'Failed to clear local cache'))
       }
       if (
-        localMetadata.owner === ownerName &&
+        matchesIdentifierInput(localMetadata.owner, ownerInput) &&
         localMetadata.name != null &&
-        localMetadata.name.toLowerCase() !== projectName.toLowerCase()
+        !matchesIdentifierInput(localMetadata.name, projectNameInput)
       ) {
         // If project name mismatch, ask user whether to open the cached project or not, to avoid potential data loss by clearing cache
-        const stillOpenTarget = await helpers.confirmOpenTargetWithAnotherInCache(projectName, localMetadata.name)
+        const stillOpenTarget = await helpers.confirmOpenTargetWithAnotherInCache(projectNameInput, localMetadata.name)
         signal.throwIfAborted()
         if (stillOpenTarget) {
           localData = null
           this.localCacheHelper.clear().catch((e) => capture(e, 'Failed to clear local cache'))
         } else {
+          if (localMetadata.owner == null) throw new Error('Local cache owner expected')
           helpers.openProject(localMetadata.owner, localMetadata.name)
           throw new Cancelled('Open another project')
         }
@@ -242,8 +259,8 @@ export class Editing extends Disposable {
     loadFromLocalCacheReporter.report(1)
 
     // For projects not owned by the signed-in user, we prefer to load the published version.
-    const preferPublishedContent = this.signedInUsername !== ownerName
-    const cloudData = await this.cloudHelpers.load(ownerName, projectName, preferPublishedContent, signal)
+    const preferPublishedContent = !matchesIdentifierInput(this.signedInUsername, ownerInput)
+    const cloudData = await this.cloudHelpers.load(ownerInput, projectNameInput, preferPublishedContent, signal)
     signal.throwIfAborted()
     loadFromCloudReporter.report(1)
 
@@ -259,6 +276,7 @@ export class Editing extends Disposable {
       }
     }
     await this.project.load(finalData, signal)
+    this.updateMode()
     signal.throwIfAborted()
     projectLoadReporter.report(1)
   }

spx-gui/src/pages/community/project.vue

@@ -54,7 +54,7 @@ const {
   refetch: reloadProject
 } = useQuery(
   async (ctx) => {
-    const p = new SpxProject(props.owner, props.name)
+    const p = new SpxProject()
     ;(window as any).project = p // for debug purpose, TODO: remove me
     const serialized = await cloudHelpers.load(props.owner, props.name, true, ctx.signal)
     await p.load(serialized)
@@ -96,7 +96,12 @@ watch(
   }
 )
 
-const isOwner = computed(() => props.owner === getSignedInUsername())
+const isOwner = computed(() => {
+  const signedInUsername = getSignedInUsername()
+  const projectOwner = project.value?.owner
+  if (signedInUsername == null || projectOwner == null) return false
+  return projectOwner === signedInUsername
+})
 const { data: liking } = useIsLikingProject(() => ({ owner: props.owner, name: props.name }))
 
 const projectRunnerRef = ref<InstanceType<typeof ProjectRunnerSurface> | null>(null)

spx-gui/src/pages/community/user/index.vue

@@ -20,7 +20,7 @@ const { data: user, error, refetch } = useUser(() => props.name)
     <template v-else-if="user != null">
       <UserHeader :user="user" />
       <div class="main">
-        <UserSidebar class="sidebar" :username="name" />
+        <UserSidebar class="sidebar" :username="user.username" />
         <div class="content">
           <router-view />
         </div>